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Stufflt 1.5.1 is referred to on page 4 of the User's Guide. In this version of the 
Tech Notes Stack product, UnStufflt was shipped in place of Stufflt. 


If you already have Stufflt (version 1.5.1 or later), you can use it in place of 
UnStufflt. Otherwise, use UnStufflt to uncompress the Tech Notes Stack. 


The screen shot on page 5 is no longer accurate due to the software change, 
though the UnStufflt screen closely resembles the screen printed. The 
procedure is the same as outlined in step 4, though the location of the Extract 
button was changed. 


We hope you enjoy this innovative method for accessing Macintosh Technical 
Notes. 


Macintosh Tech Notes Stack Release Note June 1, 1989 
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The Developer Technical Support Technical Notes Stack consists of a HyperCard® stack and an 
accompanying folder which contains the Technical Note illustrations in PICT file format. The stack 
and folder are shipped as a single file (Technical Notes Stack 3.0.sit) in a compressed format. 
[Thanks to Raymond Lau, author of Stuffit, for allowing us to use this shareware compression utility. ] 


This, the first release of the Technical Notes Stack, includes all Technical Notes written through 
December 1988 (Notes 0 - 221) as well as the complete index. This stack is meant as a supplement to 
the published Technical Notes, and it will hopefully help you get even more out of the information we 
publish in the Notes. 


With this stack and HyperCard, you can now search the entire set of Technical Notes electronically as 
well as copy the code samples directly into your programming environment. This Users Guide is 
meant to help you get started with the stack and to serve as a reference for those features of the 
stack which may not be completely self-explanatory. 


Thanks for using the Technical Notes Stack, and thanks especially for writing the great software 
which makes the Macintosh the success that it is. 


Macintosh Technical Notes Stack 


Requirements for Use 
To use the Technical Notes stack, you need the following: 


* A Macintosh Plus or later model with a minimum of one megabyte of memory. 

* A hard disk with a minimum of 2.5 megabytes of free space. (You only need 
approximately 1.5 megabytes of free space to use the stack, but installation 
requires the additional space.) 

*  HyperCard 1.2 or later and a Home stack. We recommend using the latest version of 
HyperCard, which is currently 1.2.2. | 

* A LaserWriter® or ImageWriter® printer if you wish to print the Notes or the 
illustrations. 


Installing the Technical Notes Stack 


1) You need a copy of the shareware compression utility Stuffit 1.5.1 to decompress 
and install the stack and accompanying illustrations. You can obtain this utility on 
AppleLink in the Developer Services BBS (8 Developer Services:Developer 
Technical Support:Macintosh:Compression Utilities) as well as on other electronic 
services and BBS systems. Figure 1 provides the information necessary to obtain a 
copy of Stuffit 1.5.1 if you do not have access to any electronic services or user 
group libraries. 


À shareware file archival utility by... 
...Raymond Lau 


VERSION 1.5.1 
Copyright © 1987, 1988, Raymond Lau. All Rights Reserved. 


Usage: You may try Stuffit out for 15 days. Afterwards, if you find it useful, please 
register your copy by sending US$20 to the author. If you would like the latest 
version sent to you, include an extra $2 ora disk & SASE. Please tell me what 
version you already have so I won't send you a duplicate! For decompression 
only, the freeware UnStuffIt utility is available. Thank you for your support. 


Raymond Lau MacNET. RayLau Usenet: raylau@dasvsl .UUCP 
100-04 70 Ave. GEnie: RayLau. eae : 
Forest Hills, N.Y. 11375-5133 CIS: 76174,2617 Commercial distrib. restricted. 
United States of America Delphi: Raymond Lau 


Thanks to David Schenfeld, Richard Outerbridge, William R. Whitford, A Weber, J.W McGuire. 


THE MACINTOSH ARCHIVE UTILITY 





Figure 1-Stufflt Utility Information 


2) Copy the file “Technical Notes Stack.sit” from the distribution floppy disk to your 
hard disk, and put the floppy disk away to use as a backup. If you have a copy of 
Stuffit on your disk, the file should appear with the icon shown in Figure 2. 
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Technical Notes Stack 3.0.sit 
Figure 2-Compressed File Icon 


3) Double-click on the file "Technical Notes Stack 3.0.sit” on your hard disk, and if you 
have a copy of Stuffit on your disk, you should get the dialog box in Figure 3. If 
your Desktop file has not been updated, you may need to open this file from within 
the Stuffit application. 





Technical Notes Stack 3.0.sit 









ile Name lupe Crea Size #Saved 
echnical Notes Stack f: 1566203 508 "3 





1 items, ?68k archive, 1529k decompressed. 


Selde 
Add Multiple [ | Extract J | Delete | | Rename Info 


Real ity: 36224k free. 





Figure 3-Archive Dialog Box 


4) Choose “Technical Notes Stack f:” by clicking on it, then click on the Extract 
button to place this folder where you would like it on the hard disk. You will be 
prompted with the dialog box in Figure 4. When you have chosen the location of the 
folder, click on the Save button to begin installation. 
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Figure 4-Extract Standard File Dialog 


5) If there are no problems with the installation, your Macintosh will beep indicating 
that the process is complete. You can now quit Stuffit, and you should have a folder 
named "Technical Notes Stack f" (unless you renamed it) on your hard disk. 


6) The last step of installation is deleting the "Technical Notes Stack 3.0.sit" file from 
your hard disk. You may want to work with the stack first, however, to make sure 
there are no problems which would require you to reinstall it, If you need to reinstall 
the stack or the illustrations for any reason, first drag the entire "Technical Notes 
Stack f" folder to the trash before rerunning these installation instructions. 


Important Notes on Using the Technical Notes Stack 


You can put the Technical Notes stack and the TN.PICT folder anywhere on your hard disk, but they 
must remain at the same directory level (i.e., both in the same folder or both in the root directory of 
the hard disk). Installation puts both the stack and the TN.PICT folder in another folder, “Technical 
Notes Stack f." In addition, you must not rename the TN.PICT folder or any of the PICT format files 
it contains. The Technical Notes stack currently uses the exact names to locate the illustrations, so if 
you rename a file, the stack will not be able to find it. 


The Technical Notes stack is designed to be easy to use. The interface is as simple as possible, and if 
you do not know what a particular item does, you can usually click on it to see what happens; you will 
not damage the stack (at least we hope you won't). 
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Each Technical Note has its text locked, so you cannot accidently delete some important piece of 
information. You can, however, copy or modify the text if you wish. Refer to the section on 
Technical Note Cards for more information on how to use the Lock/Unlock button to accomplish 
this. 


If you cannot find a topic or subject in one of the three directories, you can always use the 
HyperCard Find command from almost anywhere in the stack. Simply type Command-F, enter your 
search word or phrase between the quotation marks, then press Return. 


The stack consists of the following five different types of cards: 


e Opening Card 

e Listing by Number 

e Listing by Subject 

e Complete Index 

e Technical Note Cards 


The rest of this User's Guide details the different types of cards and the options which you have 
available to you from each card type. In addition, we have included information about customizing 
the stack and using the ' xcMp ' and ' XFCN' resources in your own stacks. 
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Macintosh Technical Notes Stack 


Opening Card 


When you open the Technical Notes stack, it will cycle through three cards before stopping at the 
Opening Card, which is shown in Figure 5. (Note: If you do not like the small delay of cycling 
through the first three cards, you can remove them without affecting the stack or its functionality, 
or, if you install a Technical Notes Stack button on your Home Card, you can link directly to the 
Opening Card .) i 


Stack Ver sien: 3.0 


HyperCard Version: 1.2.2 y Developer 


System Version: 6.0.3 t5 ar 
Monitors Setting: bit, Color FS i Technical Support 


M . 





Figure 5-Opening Card 


The Opening Card contains a Version Information Box which is updated each time you open the 
stack after restarting HyperCard. This Version Information Box provides the following information: 
stack version, HyperCard version, System Software version, and minimal video monitors settings. 
This feature is provided with an 'xFNC' resource, which is available for licensing for use in your own 
stacks. Refer to the section on Licensing Information for more details on this and other resources 
included in this stack. 


If you report bugs in this stack to Macintosh Developer Technical Support, please include the 
information which is provided in the Version Information Box along with a description of the bug. 
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Stack Version 

The stack version displays the current version of the Technical Notes stack. This version number will 
be updated automatically in future releases and updates. The current release, version 3.0, is the first 
official release of this stack from Developer Technical Support, and it contains all Macintosh 
Technical Notes released as of December 1988. This release covers Notes 0-221 and includes an index. 


HyperCard Version 

The HyperCard version displays the version of HyperCard in use on your Macintosh. This stack 
requires HyperCard version 1.2 or later, and Developer Technical Support recommends that you 
always use the latest released version (currently 1.2.2) with this stack. 


System Software Version 

The System Software version displays the System Software version running on your Macintosh. This 
Stack has been tested with System Software 6.0.2 and 6.0.3, and Developer Technical Support 
recommends you use one of these versions (or later) with this stack. This stack may work with 
earlier versions of the System Software, but we really would like you to use the current version. 


Monitors Setting 

The monitors setting displays the settings for your primary video device. Current versions of 
HyperCard can only display the special visual effects used in this stack when this device is set to a bit 
depth of one (two colors or blank and white). If you are using a Macintosh II or IIx, you can control 
both the bit depth and the choice of color or blank and white (and grays) with the Monitors control 
panel device (cdev). Other Macintosh models are already set to a bit depth of one and black and 
white if using their built-in monitor. You can still use the stack with a bit depth greater than one, but 
you will not see the special visual effects. 


Clicking almost anywhere on this card (or pressing Right Arrow, if it is available) will take you to the 
next type of card, Listing by Number, which lists all the Technical Notes which are available in this 
Stack in numerically ascending order. 


You can return to the Opening Card at any time by entering the following in the message box 
(Command-M): go card "TitleCard". 


Opening Card 9 


Macintosh Technical Notes Stack 





Navigation Buttons 


Navigation buttons are located on the bottom of all card types except the Opening Card, and you 
can use these to navigate your way through the stack. Figure 6 illustrates these navigation buttons 
with the Listing by Number selection selected. 



















by Muriber T Listing by Subject | m Complete Index : 












! Listing [Go Back if 


Figure 6-Navigation Buttons 


When you want to move to another type of Technical Note directory, switch between a Technical 
Note card and a directory, or close the Technical Notes stack and go to your HyperCard Home Card, 
you should use the following navigation buttons: 


e Home 
The Home button is located in the lower left corner of all card types except the 
Opening Card, and clicking on this button from anywhere in the stack will take you 
to your HyperCard Home Card. 


e Listing by Number 
The Listing by Number button is located to the right of the Home button at the 
bottom of all card types except the Opening Card, and clicking on this button from 
anywhere in the stack will take you to the Listing by Number card. When you are 
viewing the Listing by Number card, this button will be highlighted, and clicking on 
it will have no effect. 


* Listing by Subject 
The Listing by Subject button is located in the middle at the bottom of all card 
types except the Opening Card, and clicking on this button from anywhere in the 
stack will take you to the Listing by Subject card. When you are viewing the Listing 
by Subject card, this button will be highlighted, and clicking on it will have no 
effect. 


e Complete Index 
The Complete Index button is located to the right of the Listing by Subject button 
at the bottom of all card types except the Opening Card, and clicking on this button 
from anywhere in the stack will take you to the Complete Index card. When you are 
viewing the Complete Index card, this button will be highlighted, and clicking on it 
will have no effect. 


a aa o E ee a M 
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e Go Back 
The Go Back button is located in the lower right corner of the Listing by Number, 
Listing by Subject, and Complete Index cards. This button is only active when you 
arrive at one of these three cards from a Technical Note Card. Clicking on this 
button returns you to the last Technical Note card you saw, regardless of how many 
times you move between other card types. 


This button changes to a Print button when you are looking at a Technical Note 
card, and details on using the Print button are in the section on Technical Note 
Cards. 





Note: 





These navigation buttons appear on several different card types, but since their function 
does not change, this is the only section which includes a definition of how they are used. 
References to "navigation buttons" in other sections of this document refer these 
definitions. 
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Navigation Buttons 1 


Macintosh Technical Notes Stack 


Listing by Number 


The Listing by Number card presents a directory of all available Technical Notes in a numerically 
ordered, scrolling list as shown in Figure 7. This directory is most useful when scarching for a particular 
Technical Note when you know the number or the title. 


"s "uL n '"- 2 
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B O00 - About Macintosh Technical Notes | 
001 - Desk Accessories and System Resources 
DO2 - Compatibility Guidelines 
003 - Command- Shift-Number Keys 
004 - Error Returns from GetNewDialog 
005 - Using Modeless Dialogs from Desk Accessories 
006 - Shortcut for Owned Resources 
007 - A Few Quick Debugging Tips 
B| 008 - RecoverHandle Bug in AppleTalk Pascal Interfaces 
j) 009 - Will Your AppleTalk Application Support Internets? 
010 - Pinouts 
011 - Memory-Based Mar Write File Format 
012 - Disk-Based Mac Write Format 
d 013- MacWrite Clipboard Format F 
|| 014- The INIT 31 Mechanism 
1 015- Finder 4.1 | 
016 - Mac Works XL i 


I rone JUMMNTETTITETTTNNI B cometete index € [co Back 


AAA APA SAP 





Figure 7-Listing by Number 


You can use the scroll bars to move through the list when searching for a particular Note. Once you 
find the Note for which you are searching, you can simply click anywhere on the that name in the list 
and you will go directly to that Note. To return to this directory from any card in the stack, except 
the Opening Card, click on the Listing by Subject navigation button. If you would prefer searching 
for Technical Notes from another type of directory, use the Listing by Subject or Complete Index 
navigation buttons. 
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Listing by Subject 


The listing by Subject card presents a directory of all available Technical Note subjects (taken from 
Technical Note #0) in an alphabetically ordered, scrolling list on the left side of the card as shown in 
Figure 8. This list is the "Subject Selection Field," and you use it to choose a particular subject area. 


mr Unum ' * . AG "am m a ’ NO zx 
eat wh rig La. [1 En EE : Min " Les wi ate oie as ie hae HUS 
Dee ilU t. Roco tS EF UI “a $e .- EE d Mace MEUM 


ADB 
l| AppleShare 002 - Compatibility Guidelines Jar 
025 - Don't Depend on Register AS Within Trap Patches 
AppleTalk Manager 044 - HFS Compatibility 
| Applications G83 - System Heap Size Warning 
| OPP 100 - Compatibility with Large-Screen Displays 
CD ROM 103 - Using Max ApplZone and MoveHHi from Assembly 
Compatibili 117 - Compatibility : Why and How 
p » 129 - _SysEnvirons: System 6.0 and Beyond 
Control Manager 155 - Handles and Pointers—ldentity Crisis 
Control Panel 156 - Checking for Specific Functionality 
i 194 - WMgrPortability 
Debugging ET 203 - Don't Abuse the Managers 
Desk Accessories 208 - Setting and Restoring AS 
; 212 - The Joy of Being 32-Bit Clean 
Device Manager 213 - _StripAddress: The Untold Story 


|| Dialog Manager 
: Disk Initialization Package 
Event Meneger 


| [ Home || Listing by Number 


Figure 8-Listing by Subject 





You can use the scroll bars to move through the Subject Selection Field when searching for a particular 
topic. Once you find the topic for which you are searching, you can simply click anywhere on the 
name in the Subject Selection Field, and the stack will display a list of all Technical Notes which 
address this topic in a numerically ordered, scrolling list on the right side of the card (Figure 8 
illustrates the display if you were to choose "Compatibility" as your topic). This list is the "Technical 
Note Selection Field," and you use it just as you would the Listing by Number card. Simply click 
anywhere on the title of the Technical Note which interests you, and you will go directly to that Note. 


If you want to move sequentially (or randomly) through a complete subject area, you can use the 
Listing by Subject navigation button from each Technical Note card, and it will return you to the 
same choice in the Listing by Subject card so you do not have to repeat your topic search for each 
Note which addresses that topic. If you would prefer searching for Technical Notes from another 
type of directory, use the Listing by Number or Complete Index navigation buttons. 
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Complete Index 


The Complete Index card presents a directory of all available indexed Technical Note terms, phrases, 
and topics (taken from the Technical Note Index) in an alphabetically ordered, scrolling list on the 
left side of the card. This list is the "Index Word Selection Field," and you use it just as you would the 
Listing by Subject card. Simply click anywhere on the indexed entry in the Index Word Selection 
Field, and the stack will display a list of all Technical Notes which include a reference to this topic in a 
numerically ordered, scrolling list on the right side of the card (Figure 9 illustrates the display if you 
were to choose "Launch" as your topic). As with the Listing by Subject card, this list is the "Technical 
Note Selection Field." 


| Macintosh T Notes - Complete Index ; 


aL 
LAP 
large capacity media 052 - Calling Launch From a High-Level Language 
large-sereen displays 126 - Sublaunching: Playing the Shell Game 
Laser Prep 180 - MultiFinder Miscellanea 
LaserShare 208 - MultiFinder Revisited: The 6.0 System Release 
LaserWriter 
LaserWriter driver 
Launch 
LaunchF lags 
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Figure 9-Complete Index 


You can use the scroll bars to move through the Index Word Selection Field, but since there are 
currently over 1,500 entries, this might take some time. To help you move quickly through this large 
list, the stack provides an “Index Field Scroll Controller” to the left of the Index Word Selection Field. 
Simply clicking on a tab of the Index Field Scroll Controller will begin listing the chosen entries under 
the alphabetic character on that tab (the “Misc” tab includes those entries which begin with numbers 
or non-alphabetic characters (i.e., @ operator, 32-bit clean)).. In the example in Figure 9, the “L” tab 
is chosen. 


Once you find the indexed entry which interests you and have chosen it to display the Technical 
Notes which include a reference to it, you can simply click anywhere on the title of the Technical 
Note which interests you, and you will go directly to that Note. 
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If you want to move sequentially (or randomly) through every Note which includes a reference to a 
particular index entry, you can use the Complete Index navigation button from each Technical Note 
card, and it will return you to the same choice in the Index Word Selection Field so you do not have to 
repeat your search for each Note which includes a reference to that indexed entry. If you would 
prefer searching for Technical Notes from another type of directory, use the Listing by Number or 
Listing by Subject navigation buttons. 


E E ee ee ee ee MM 


Complete Index 15 


Macintosh Technical Notes Stack 
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Technical Note Cards 


You will probably spend most of your time with this stack on Technical Note Cards, since these cards 
contain the actual Technical Notes in a scrolling field. Figure 10 displays a typical Technical Note 
Card, and in this case it is Technical Note #0, which provides important information about Technical 
Notes and this Technical Notes Stack. 


|| Stack Version 3.0 Harch 1, 1989 


| Technical Note #0 (this card) accompanies each release of Technical Notes. 
Hi This stack is the first official release of Technical Notes in HyperCard 
iformat, and it includes all Macintosh Technical Notes (0-221) released as of 
December 1988. 


i You can access the Notes by number, subject, and index, or you may want to use 
d HyperCard's built-in search function to find a topic if the index does not list 
jit. (To use the search function, type Command-F, enter your search word between 
: the quotation marks, then press Return.) 


i You do not need to be familiar with HyperCard to use this stack; if at any time 
; you are unclear about how something in the stack works, try clicking on the 
lobject in question, and its functionality should become apparent. 
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J| If there are any subjects which you would like to see treated in a Technical VE 





Figure 10-Technical Note Card (Technical Note £0) 


In addition to the standard navigation buttons, Technical Note Cards have arrow buttons located on 
either side of the Technical Note title at the top of the card. Clicking on these arrow buttons is the 
same as pressing Left Arrow or Right Arrow, it takes you to the Technical Note Card numerically 
preceding (Left Arrow) or following (Right Arrow) the current card. These buttons scroll continually if 
you hold down the mouse button when you click on them (this is different from most HyperCard 
buttons which only move one card at a time for each time you click on them), and using this feature 
you can scroll through several Technical Notes very quickly without needing to go back to one of the 
directories to choose another Note. 


However, since you can get to each of the three types of Technical Note directories from a 
navigation button, the "Go Back" button does not appear on Technical Note Cards, and it is 
replaced by the “Print” Control button, one of the three types of Control buttons which can appear 
on Technical Note Cards. The Control buttons “Print,” "Display Graphic Image,” and “Lock/Unlock” 
and are documented later in this section, but for now you should know that they are unique to 
Technical Note Cards, and they control different functions you may want to perform on the 
individual Technical Notes. 


—————— MM M kk ee 
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In most cases, each Note occupies only one card, but you should be aware that longer Notes are split 
across several numerically ordered cards. Notes which require more than one card are labeled "Card 1 
of n" at the top of the field where n is the total number of cards, and the Technical Note number at 

the top of the card will include a letter (i.e., a, b, c...) to indicate the order of that card in the series. 
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Figure 11-Technical Notes Which Require Multiple Cards 


Figure 11 illustrates an example of a Note which is split across several cards, both on the Listing by 
Number card and on the third and final card of the third set of cards (e.g., Card 3 of 5 on Technical 
Note #117c). 


Control Buttons 

Technical Note Cards use three types of Contro! buttons: Print, Display Graphic Image, and 
Lock/Unlock. Every Technical Note Card has a Print and Lock/Unlock button, but only those which 
use accompanying illustrations use the Display Graphic Image button. 


* Print 
The Print button located in the lower right corner of the Technical Note Cards prints the text 
of the current Technical Note Card. When you click on the Print button, you will see the Print 
Status dialog box shown in Figure 12. When this dialog disappears, you can continue working 
in the stack. If you wish to cancel printing, press Command-period until the dialog 
disappears. 


Now Printing... 


Type command-periad to stop 





Figure 12-Text Print Status Dialog Box 


a —M———— 
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Macintosh Technical Notes Stack 


The Print button on the Technical Note Cards will not print the associated illustrations; you 
must print the illustrations from the window in which they are displayed, which you can 
access with the Display Graphic Image button shown in Figure 13 and documented in the 
next section. If a Technical Note Card does not have this button, there are no illustrations 
which accompany the Note. 


e Display Graphic Image 
The Display Graphic Image button, if it exists for a particular Note (e.g., if the Note has 
illustrations which accompany it), is located in the lower right corner of the text field where 
the Note is displayed. If there is more than one illustration, there will be multiple buttons 
from which to choose. The icon for the Display Graphic Image button is shown in Figure 15, 
and its location on a Technical Note Card follows in Figure 14. 










Version Terror 


| 4189: Yersion Territory 
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|| See also: The Finder Interface 
Technical Note #48: Bundles 







A Written by: Darin Adler àpril 2, 1988 
dtodified by: Andrew Shebanow August 1, 1988 
d Modified by: Andrew Shebanow October 1, 1988 

















|| This Technical Note describes the ‘vers’ resource supported by Finder 6.1 and 
later versions. 

|| Changes since August 1, 1988: Updated Version to VersRec in the type 
definition. 





J Finder 6.1 introduces a feature which allows the creator of a file to idep 
ii the version of that file as well as the version of a set of files which 

H includes that file. These version numbers are stored in 'vers' resources 
each contains a BCD form of the version number and a longer version messa 


J| Home |] Listing by Number — |E Listing by Subject 


Figure 14-Display Graphic Image Button Location 





To display an illustration, click on the Display Graphic Image button. The stack will open a 
full-screen sized window to display the illustration as shown in Figure 15. You can manipulate 
this window by scrolling, resizing, zooming, and moving to a different location on the 
screen. (Note: Under MultiFinder, currently you can switch to another layer while displaying 
a graphic image, but you cannot access the HyperCard layer.) 
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Leeked [ ] 
Finder 
— System Software Version 6.0 from vers 2 


Kind: System document pesca ee 
Size: 106,953 bytes used, 105K on disk 


Where: beet Ween, SCSLO 
Created: Tue, Mar B, 1988, 12 00 PM 
Modified: Fri, Mar 25, 1968, 4:51 FM 


Versiea: 6.1, OApple Computer, inc. 
1983-88 


Suggested Memory Size (K): 320 


Application Memor y Size (K): 


Stack Version 3.0 
March 1, 1989 





Figure 15-Full-Screen Sized Graphic Image Window 


You can scale a illustration to fit on entirely your screen if it is too large to be displayed when 
it first opens. Pressing Command-F toggles between the “Reduce-to-Fit” and full-screen 
windows. An example of reducing a window to fit is shown in Figure 16. 
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Figure 16-Reduce-to-Fit Graphic Image Window 


The Print button located in the lower left corner of the full-screen sized Graphic Image 
Window (see Figure 15 for location) prints the illustration in the current window. When you 
click the Print button, you will see the Print Status dialog box shown in Figure 17. When this 
dialog disappears, you can continue working in the stack. If you wish to cancel printing, 
press Command-period until the dialog disappears. 


Now printing: “PICT - 189" 


To cancel, press command-period. 
Pages to print: 1 





Figure 17-Graphic Image Print Status Dialog Box 


When you are finished viewing or printing the illustration, you can close the window by either 
clicking in the close box or pressing Command-W. 
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e Lock/Unlock 
The Lock/Unlock button prevents you from accidently deleting or altering the text of the 
Technical Notes, but it allows you to copy the text for your own use. This button first 
appears as a closed padlock in the upper right corner of the text field where the Note is 
displayed as shown in Figure 18. 


H 4000: About Macintosh Technical Notes 


[NET NN | 


M Stack Yersion 3.0 March 1, 1989 


H| Technical Note #0 (this card) accompanies each release of Technical Notes. 
This stack is the first official release of Technical Notes in HyperCard 
format, and it includes all Macintosh Technical Notes (0-221) released as of 


il December 1988. 


1 You can access the Notes by number, subject, and index, or you may want to use 
d HyperCard's built-in search function to find a topic if the index does not list 
lit. (To use the search function, type Command-F, enter your search word between 
|| the quotation marks, then press Return.) 


i You do not need to be familiar with HyperCard to use this stack; if at any time 
you are unclear about how something in the stack works, try clicking on the 
object in question, and its functionality should become apparent. 


IIE there are any subjects which you would like to see treated in a Technical 


ILLE 


J| Home |: Listing by Number 





Figure 18-Lock/Unlock Button in Locked Mode 


If your HyperCard User Level is higher than Browsing (1), then clicking on the Lock/Unlock 
button will change it to an open padlock and unlock the Technical Note text field so you can 
select text with which to work as shown in Figure 19. 
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: About Macintosh Technical Notes 
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B| Stack Tersion 3.0 March 1, 1989 


| Technical Note #0 (this card) MATER EE OEER IK TIER LI 
This ztack is the first official release of Technical Hotes in HyperCard 

‘| format, and it includes all Macintosh Technical Notes (0-221) released as of 

‘December 1989. 


| You can access the Hotes by number, subject, and index, or you may vant to use 
‘|HyperCard’s built-in search function to find a topic if the index does not list 
ELS (To use the search function, type Command-F, enter your search mord between 
{the quotation marks, then press Return.) 


You do not need to be familiar with HyperCard to use this stack; if at any time 
| you are unclear about how something in the stack works, try clicking on the 

; object in question, and its functionality should become apparent. 

I| If there are any subjects which you would like to see treated in a Technical 


[ Home |] Listing by Number Listing by Subject Complete Index ; 


Figure 19-Lock/Unlock Button in Unlocked Mode 





If your HyperCard User Leve! is either Authoring (4) or Scripting (5), any changes you make to 
the stack, including the text of the Technical Note Cards, wil! remain when you close that 
card (although the card will revert to the locked mode). If your User Level is anything less 
than Authoring or Scripting, all changes you make will be lost, as the card will revert to its 
original text and the locked mode when you close it. 
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Customizing the Technical Notes Stack 


You will probably spend most of your time with this stack on the Technical Note Cards, but like most 
of Developer Technical Support, you will probably want to make some changes to the stack or at 
least poke around in the scripts to see exactly how it all works. This is fine with us, but we offer some 
advice on using caution as well as a few techniques to keep you out of trouble. 














Warning: Do not distribute modified versions of this stack without clearly 
documenting the changes in the scripts and identifying the stack on the 
Opening Card as a customized version. If you implement features which 
you would like to see included in the released version of this stack, please 
send them to Macintosh Developer Technical Support at one of the 
addresses listed in Technical Note #0. 


The Technical Notes Stack Updater may make sweeping changes to the stacks it updates. These 
changes may include not only the Notes in the stack, but also the scripts which run the stack. These 
updates will not be able to account for any modifications you make, so although the update 
should still work, your changes will probably be lost. 


Techniques to Avoid Trouble 

e Always work on a copy of the stack. 

e Always keep an original copy of the stack in a safe place as a backup (The 
compressed file on the distribution disk is good for this purpose if you don't mind 
rerunning the installation process). 

e Make your changes in modules, so you can restore them after an update (i.e., instead 
of changing the existing handlers in a number of places, write your own handlers and 
call them from within the existing code). 

e Always thoroughly document your changes with clear comments, so you can 
differentiate between your modifications and our released versions. 

e Always back up your stack before updating, then carefully check the new release and 
work your modifications into the new stack from your backup copy. Do not delete 
your backup copy until you are sure all the features of the stack work. 

e When in trouble, start over with the original copy of the stack. 
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Licensing Information 


The Technical Notes Stack uses two ' xcMp' and two ' xFCN' resources developed and maintained 
at Apple Computer, Inc. for various functions. The resources are as follows: 


' XCMD' Resources 
* TNPict 
* PrintOut 
'XFCN' Resources 
ee SysEnv 
* Dialoq 


and are copyrighted by Apple Computer, Inc. You may, however, licence all of these resources for use 
in your own products. For more information about licensing, contact: 


Software Licensing 

Apple Computer, Inc. 

20525 Mariani Avenue, M/S 38-1 
Cupertino, CA 95014 

(408) 974-4667 

AppleLink: SW. LICENSE 
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Update Information 


Developer Technical Support will be updating the Technical Notes Stack quarterly and sending the 
updates in the regular developer mailings. We have designed an Updater stack which will contain new 
and revised Technical Notes as well as new or revised scripts to control the Technical Notes Stack. 


Updates will be ordered sequentially, so you will need each update; if you do not install one update, 
the next one may not work. 


We want this stack distributed as widely as possible, so updates will also be available on AppleLink in 
the Developer Services bulletin board (in a compressed format) and other electronic sources. You 
can also order the Technical Notes Stack and updates from APDA. Refer to Technical Note #0 for 
more information on APDA. 


a MM M —— 


Update Information 25 


APPLE SOFTWARE LICENSE 


PLEASE READ THIS DOCUMENT CAREFULLY BEFORE USING THE 
SOFTWARE. BY USING THE SOFTWARE, YOU ARE AGREEING TO 
BE BOUND BY THE TERMS OF THIS LICENSE. IF YOU DO NOT 
AGREE TO THE TERMS OF THIS LICENSE, PROMPTLY RETURN THE 
UNUSED SOFTWARE TO THE PLACE WHERE YOU OBTAINED IT AND 
YOUR MONEY WILL BE REFUNDED. 


1. License. The application, demonstration and system software (the 
"Software") and related documentation are licensed to you by Apple. You 
own the disk on which the Software is recorded but Apple retains title to the 
Software. This License allows you to use the Software on a single Apple 
computer and make one copy of the Software in machine-readable form for 
backup purposes only. You must reproduce on such copy the Apple 
copyright notice and any other proprietary legends that were on the original 
copy of the Software. You may also transfer the Software, the backup copy 
of the Software, the related documentation and a copy of this License to 
another party provided the other party reads and agrees to accept the terms 
and conditions of this License. 


2. Restrictions. The Software contains copyrighted material, trade secrets, 
and other proprietary information and in order to protect them you may not 
decompile, reverse engineer, disassemble or otherwise reduce the Software 
to a human-perceivable form. You may not modify, network, rent, lease, 
loan, sell, distribute or create derivative works based upon the Software in 
whole or in part. You may not electronically transfer the Software from one 
computer to another over a network. 


3, Termination. This License is effective until terminated. You may 
terminate this License at any time by destroying the Software and all copies 
thereof, This License will terminate immediately without notice from Apple 
if you fail to comply with any provision of this License. Upon termination you 
must destroy the Software and all copies thereof. 


4. Export Law Assurances. You agree and certify that neither the 
Software nor any other technical data received from Apple, nor the direct 
product thereof, will be exported outside the United States except as 
authorized in advance by Apple, in writing, and as permitted by the laws 
and regulations of the United States. 


5, Government End Users. 

(a) If this Software is acquired by or on behalf of a unit or agency of the 
United States Government this provision applies. This Software: (i) was 
developed at private expense, and no part of it was developed with 
government funds; (ii) is a trade secret of Apple for all purposes of the 
Freedom of Information Act; (iii) is “commercial computer software" subject 
to limited utilization as provided in the contract between the vendor and the 
gcvernmental entity; and (iv) in all respects is proprietary data belonging 
solely to Apple. 

(b) For units of the Department of Defense (DOD), this Software is sold only 
with "Restricted Rights" as that term is defined in the DOD Supplement to the 
Federal Acquisition Regulations ("DFARS") 52.227-7013 (c) (1) Gi) and use, 
duplication or disclosure is subject to restrictions as set forth in subparagraph 
(c) (1) Gi) of the Rights in Technical Data and Computer Software clause at 
DFARS 52.227-7013, Manufacturer: Apple Computer, Inc., 20525 Mariani 
Avenue, Cupertino, California 95014. 

(c) If this Software was acquired under a GSA Schedule, the Government has 
agreed: (i) to refrain from changing or removing any insignia or lettering 
from the Software that is provided or from producing copies of manuals or 
disks (except one copy for backup purposes); (ii) title to and ownership of this 
Software and any reproductions thereof shall remain with Apple; (iii) use of 
this Software shall be limited to the facility for which it is acquired; and (iv) if 
use of the Software is discontinued at the installation specified in the 
purchase/delivery order and the Government desires to use it at another 
location, it may do so by giving prior written notice to Apple, specifying the 
type of computer and new location site. 

(d) Government personnel using this Apple Software, other than under a 


DOD contract or GSA Schedule, are hereby on notice that use of this 
Software is subject to restrictions which are the same as, or similar to, those 
specified above. 


6. Limited Warranty on Media. Apple warrants the disks on which the 
Software is recorded to be free from defects in materials and workmanship 
under normal use for a period of ninety (90) days from the date of purchase 
as evidenced by a copy of the receipt. Apple's entire liability and your 
exclusive remedy will be replacement of the disk not meeting Apple's 
limited warranty and which is returned to Apple or an Apple authorized 
representative with a copy of the receipt. Apple will have no responsibility 
to replace a disk damaged by accident, abuse or misapplication. ANY 
IMPLIED WARRANTIES ON THE DISKS, INCLUDING THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) 
DAYS FROM THE DATE OF DELIVERY. THIS WARRANTY GIVES YOU 
SPECIFIC LEGAL RIGHTS, AND YOU MAY ALSO HAVE OTHER RIGHTS 
WHICH VARY FROM STATE TO STATE. 


7. Disclaimer of Warranty on Software. You expressly acknowledge 
and agree that use of the Software is at your sole risk. The Software and 
related documentation are provided "AS IS" and without warranty of any 
kind and Apple EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESS OR 
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
APPLE DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE 
SOFTWARE WILL MEET YOUR REQUIREMENTS, OR THAT THE 
OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR- 
FREE, OR THAT DEFECTS IN THE SOFTWARE WILL BE CORRECTED. 
FURTHERMORE, APPLE DOES NOT WARRANT OR MAKE ANY 
REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE 
OF THE SOFTWARE OR RELATED DOCUMENTATION IN TERMS OF THEIR 
CORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. NO ORAL 
OR WRITTEN INFORMATION OR ADVICE GIVEN BY APPLE OR AN APPLE 
AUTHORIZED REPRESENTATIVE SHALL CREATE A WARRANTY OR IN 
ANY WAY INCREASE THE SCOPE OF THIS WARRANTY. SHOULD THE 
SOFTWARE PROVE DEFECTIVE, YOU (AND NOT APPLE OR AN APPLE 
AUTHORIZED REPRESENTATIVE) ASSUME THE ENTIRE COST OF ALL 
NECESSARY SERVICING, REPAIR OR CORRECTION. SOME STATES DO 
NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE 
EXCLUSION MAY NOT APPLY TO YOU. 


8. Limitation of Liability, UNDER NO CIRCUMSTANCES INCLUDING 
NEGLIGENCE, SHALL APPLE BE LIABLE FOR ANY INCIDENTAL, SPECIAL 
OR CONSEQUENTIAL DAMAGES THAT RESULT FROM THE USE OR 
INABILITY TO USE THE SOFTWARE OR RELATED DOCUMENTATION, 
EVEN IF APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE HAS BEEN 
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO 
NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR 
INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE ABOVE LIMITATION 
OR EXCLUSION MAY NOT APPLY TO YOU. 

In no event shall Apple's total liability to you for all damages, losses, and 
causes of action (whether in contract, tort (including negligence) or otherwise) 
exceed the amount paid by you for the Software. 


9. Controlling Law and Severability. This License shall be govemed by 
and construed in accordance with the laws of the State of California, except 
that body of California law concerning conflicts of law. If for any reason a 
court of competent jurisdiction finds any provision of this License, or portion 
thereof, to be unenforceable, that provision of the License shall be enforced 
to the maximum extent permissible so as to effect the intent of the parties, 
and the remainder of this License shall continue in full force and effect. 


10. Complete Agreement. This License constitutes the entire 
agreement between the parties with respect to the use of the Software 
and related documentation, and supersedes all prior or 
contemporaneous understandings or agreements, written or oral, 
regarding such subject matter. 
2/20/89 
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#129: _SysEnvirons: System 6.0 and Beyond 


Revised by: Guillermo Ortiz & Dave Radcliffe October 1989 
Written by: Jim Friedlander May 1987 


This Technical Note discusses changes and enhancements in the SysEnvirons call in System 
Software 6.0 and later. 

Changes since April 1989: Added machineType constants for the Macintosh Portable and 
IIci. Also added keyBoardType constants for the Portable and ISO keyboards. 





_SysEnvirons and New Machines 


.SysEnvirons is the standard way to determine the features available on a given machine, and 
its main characteristic is that it continually evolves to provide the necessary information as new 
machines and System Software appear. As originally conceived, SysEnvirons would check 
the versionRequested parameter to determine what level of information you were prepared to 
handle, but this technique means updating SysEnvirons for every new hardware product 
Apple produces. With System Software 6.0, SysEnvirons introduced version 2 of 
environsVersion to provide information about new hardware as we introduce it; this new 
version returns the same SysEnvRec as version 1. 


Beginning with System Software 6.0.1, Apple only releases a new version of _SysEnvirons 
when engineering make changes to its structure (i.e., when they add new fields to SysEnvRec); 
all existing versions will return accurate information about the machine environment even if part of 
that information was not originally defined for the version you request. For example, if you call 
_SysEnvirons with versionRequested = 1 on a Macintosh IIx, it will return a 
machineType of envMacIIx even though this machine type originally was not defined for 
version 1 of the call. 


You should use version 2 of. SysEnvirons until Apple releases a newer version. Regardless of 
the version used, however, your software should be prepared to handle unexpected values and 
should not make assumptions about functionality based on current expectations. For example, if 
your software currently requires a Macintosh II, testing for machineType >= envMacII may 
result in your software trying to run on a machine which will not support the features it requires, so 
test for specific functionality (i.e., hasFPU, hasColorQD, etc.). 


You should always check the environsVersion when returning from SysEnvirons since 
the glue always returns as much information as possible, with environsVersion indicating the 
highest version available, even if the call returns an envSelTooBig (—5502) error. 
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New Constants 


The following are new SysEnvirons constants which are not documented in /nside Macintosh; 
however, you should refer to /nside Macintosh, Volume V-1, Compatibility Guidelines, for the 
rest of the story. 


machineType | 

envMacIIx = 5 : {Macintosh IIx} 

envMacIIcx = 6 {Macintosh IIcx} 

envSE30 = 7 {Macintosh SE/30} 

envPortable = 8 {Macintosh Portable} 

envMacIIci = 9 (Macintosh IIci} 

processor 

env68030 2 4 (MC68030 processor) 
keyBoardType 

envPortADBKbd = 6 (Portable Keyboard] 
envPortISOADBKbd = 7 (Portable Keyboard (ISO) } 
envStdISOADBKbd = 8 (Apple Standard Keyboard (ISO) } 
envExtISOADBKbd = 9 (Apple Extended Keyboard (ISO)) 


Further Reference: 


* Inside Macintosh, Volume V-1, Compatibility Guidelines 
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#161: When to Call PrOpen and _PrClose 


Revised by: Pete “Luke” Alexander October 1989 
Written by: Ginger Jemigan September 1987 


This Technical Note discusses opening and closing the Printing Manager with calls to _PrOpen 
and PrClose. 

Changes since August 1989: Added code for pIdle procedure support and improved the 
error handling in the page loop. 





Introduction 


At one time, Apple recommended that developers call _PrOpen at the beginning of their 
application and PrClose at the end, before returning to the Finder. This recommendation was 
in the ancient past when an application only had to deal with a single printer driver. 


As more printer drivers became available, it became important for an application to consider the 
presence of other applications and how opening and closing the printer driver affected them. The 
user could open the Chooser at any time and change the current printer driver without the current 
application's knowledge. If an application followed the old philosophy and a user changed the 
current printer driver while running the application, the next time the user attempted to print, the 
wrong driver would be open, the Printing Manager would not be able to find the necessary 
resources, and the user would get an error. 


The Current Recommendation 


Macintosh Developer Technical Support currently recommends that applications open and close the 
printer driver each time the application uses the Printing Manager. 


MPW Pascal 


** PrintStuff will call all of the necessary Print Manager calls to print 


** a document. It checks PrError() after each Print Manager call. If an 
** error is found, all of the Print Manager open calls (i.e., PrOpen, 
**  PrOpenDoc...) will have a corresponding close call before the error 


** is posted to the user. You want to use this approach to make sure the 


** Print Manager closes properly and all temporary memory is released. 
**) 


PROCEDURE PrintStuff; 
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VAR 
copies, 
firstPage, 
lastPage, 
loop, 
numberOfCopies, 
pageNumber, 
printmgrsResFile, 
realNumberOfPagesInDoc : Integer; 
PrintError : LongInt; 
oldPort : GrafPtr; 
thePrRecHdl : THPrint; 
thePrPort : TPPrPort; 
theStatus : TPrStatus; 


BEGIN 
GetPort (oldPort); 


{rx 
UnLoadTheWorld will swap out ALL unneeded code segments and data that are NOT required 
during print time. Your print code must be a separate code segment. 

**) 


UnLoadTheWorld; 
thePrRecHdl := THPrint (NewHandle(SIZEOF(TPrint))); 


IF (MemError - noErr) AND (thePrRecHdl «» NIL) THEN 
BEGIN 
PrOpen; 
IF (PrError - noErr) THEN 
BEGIN 
{xx 
Save the current resource file (i.e. the printer driver's) 
so the driver will not lose its resources upon return from the pldleProe, 
**) 
printmgrsResFile :- CurResFile; 
PrintDefault (thePrRecHdl); 


IF (PrError = noErr) THEN 
BEGIN 
IF (PrStlDialog(thePrRecHdl)) THEN 
BEGIN 
i** 
DetermineNumberOfPagesinDoc determines the number of pages contained 
in the document by comparing the size of the document with rPage 
from the TPrInfo record (IM II-150). It returns the number of pages 
required to print the document for the currently selected printer. 


**) 


realNumberOfPagesinDoc :- DetermineNumberOfPagesinDoc 
(thePrRecHdi^^.prInfo.rPage); 


IF (PrJobDialog(thePrRecHdl)) THEN 


BEGIN 
(** 
Get the number of copies of the document that the user wants 
printed from iCopies of the TPrJob record (IM II-151). 
**) 


numberOfCopies :- thePrRecHdl^^.prJob.iCopies; 
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(** 
Get the first and last pages of the document that were requested 
to be printed by the user from iFstPage and iLastPage from the 
TPrdob record (IM [I-151). 


**) 


firstPage :- thePrRecHdl^^.prJob.iFstPage; 
lastPage :- thePrRecHdl^^.prJob.iLstPage; 


(** 
Print "all" pages in the print loop 


**) 


thePrRecHdl^^.prJob.iFstPage :- 1; 


thePrRecHdl^^.prJob.iLstPage :- 9999; 

(** 
Determine the "real" number of pages contained in the document. 
Without this test, you would print 9999 pages. 

ak} 


IF (realNumberOfPagesinDoc « lastPage) THEN 
lastPage :- realNumberOfPagesinDoc; 


(** 
Print the number of copies of the document requested by the user 


from the Print Job Dialog. 
xx} 


For copies := 1 To numberOfCopies Do 
BEGIN 
{** 
Install and call your "Print Status Dialog". 
**) 
PrintingStatusDialog := GetNewDialog(257, NIL, POINTER(-1)); 
thePrRecHdl^^,.prJob.pIdleProc := @checkMyPrintDialogButton; 


{** 
Restore the resource file to the printer driver's, 
x 


UseResFile(printmgrsResFile); 
thePrPort :- PrOpenDoc(thePrRecHdl, NIL, NIL); 


IF (PrError - noErr) THEN 
BEGIN 
(** 
Print the range of pages of the document requested by the 


user from the Print Job Dialog. 
xk) 


pageNumber := firstPage; 
WHILE ( (pageNumber <= lastPage) AND (PrError = noErr)) DO 
BEGIN 


PrOpenPage(thePrPort, NIL}; 


IF (PrError = noErr) THEN 
BEGIN 
(** 
rPage (IM II-150) is the printable area for 
the currently selected printer. By passing 
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the current enables your app to use the same 
routine to draw to the screen and the 


printer's GrafPort. 
xke] 


DrawStuff (thePrRecHdl^^.prInfo.rPage, 
GrafPtr (thePrPort), 
pageNumber); 
END; 
PrClosePage (thePrPort) ; 
pageNumber := pageNumber + 1; 
END; {** End pagenumber loop **} 
END; 
PrCloseDoc(thePrPort); 
END; (** End copies loop **} 


{** 
The printing job is being canceled by the request of the 
user from the Print Style Dialog or the Print Job Dialog 
PrError will be set to iPrAbort to tell the Print Manager 
to abort the current printing job. 
**) 
END 
ELSE 
PrSetError(iPrAbort); {** Cancel from the job dialog **)} 
END 
ELSE 
PrSetError(iPrAbort); {** Cancel from the style dialoq  **) 
END; 
END; 
IF (thePrRecHdl^^.prJob.bJDocLoop - bSpoolLoop) and (PrError - noErr) THEN 
PrPicFile(thePrRecHdl, NIL, NIL, NIL, theStatus); 


(** 


Grab the printing error before you close the Print Manager and the error disappears. 
**) 


PrintError := PrError; 


PrClose; 


(** 
You do not want to report any printing errors until you have fallen through the 
printing loop. This will make sure that ALL of the Print Manager's open calls 
have their corresponding close calls, thereby enabling the Print Manager 


to close properly and that all temporary memory allocations are released. 
**) 


IF (PrintError «» noErr) THEN 
PostPrintingErrors (PrintError); 


END; 


IF (thePrRecHdl <> NIL) THEN 
DisposHandle(Handle (thePrRecHdl)); 


IF (PrintingStatusDialog «» NIL) THEN 
DisposDialog(PrintingStatusDialog); 


SetPort (oldPort); 
END; (** PrintStuff *w) 
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**  PrintStuff will call all of the necessary Print Manager calls to print 

Lid a document. It checks PrError() after each Print Manager call. If an error 
** is found, all of the Print Manager open calls (i.e., PrOpen, PrOpenDoc...) 
** will have a corresponding close call before the error is posted to the user. 
** You want to use this approach to make sure the Print Manager closes properly 
** and all temporary memory is released. 

ax f 


void PrintStuff () 
{ 
GrafPtr oldPort; 
short copies, 
firstPage, 
lastPage, 
numberOfCopies, 
printmgrsResFile, 
realNumberOfPagesinDoc, 
pageNumber, 
PrintError; 
THPrint thePrRecHdl; 
TPPrPort thePrPort; 
TPrStatus theStatus; 


GetPort(&oldPort); 


/** 
UnLoadTheWorld will swap out ALL unneeded code segments and data that are 
NOT required during print time. Your print code must be a separate code segment. 


** f 


UnLoadTheWorld (); 
thePrRecHdl = (THPrint)  NewHandie (sizeof (TPrint)); 


/** 
Check to make sure that the memory manager did not produce an error when it allocated 
the print record handle and make sure it did not pass back a nil handie. 

**/ 

if (MemError() == noErr && thePrRecHdl '= nil) 


( 
PrOpen(); 


if (PrError() -- noErr) 
( 
/** 

Save the current resource file (i.e. the printer driver's) so the 
driver will not lose its resources upon return from the pIdleProc, 

**/ 

printmgrsResFile = CurResFile(t); 

PrintDefault (thePrRecHdl); 


if (PrError() == noErr) 
{ 
if (PrStlDialog(thePrRecHdl)) . 
{ 
/** 


DetermineNumberOfPagesinDoc determines the number of pages contained in the 
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**  PrintStuff will call all of the necessary Print Manager calls to print 
** a document. It checks PrError() after each Print Manager call. If an error 

b ** is found, all of the Print Manager open calls (i.e., PrOpen, PrOpenDoc...) 
** will have a corresponding close call before the error is posted to the user. 
** You want to use this approach to make sure the Print Manager closes properly 
** and all temporary memory is released. 
**/ 


void PrintStuff () 
{ 
GrafPtr oldPort; 
short copies, 
firstPage, 
lastPage, 
numberOfCopies, 
printmgrsResFile, 
realNumberOfPagesinDoc, 
pageNumber, 
PrintError; 
THPrint thePrRecHdl; 
TPPrPort thePrPort; 
TPrStatus theStatus; 


GetPortí(&oldPort); 


/** 
UnLoadTheWorld will swap out ALL unneeded code segments and data that are 


NOT required during print time. Your print code must be a separate code segment. 
*x*/ 


UnLoadTheWorld (): 
thePrRecHdl = (THPrint) NewHandle (sizeof (TPrint)); 


/** 
Check to make sure that the memory manager did not produce an error when it allocated 
the print record handle and make sure it did not pass back a nil handle. 

**/ 

if (MemError() == noErr && thePrRecHdl != nil) 


( 
PrOpen(); 


if (PrError() -- noErr) 
{ 
/** 

Save the current resource file (i.e. the printer driver's) so the 
driver will not lose its resources upon return from the pIdleProc. 

*x*/ 

printmgrsResFile - CurResFile(); 

PrintDefault (thePrRecHdl); 


if (PrError() == noErr) 
( 
if (PrStlDialog(thePrRecHdl)) . 
( 
/** 


DetermineNumberOfPagesinDoc determines the number of pages contained in the 
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document by comparing the size of the document with rPage from the TPrInfo 
record (IM II-150). It returns the number of pages required to print the 


document for the currently selected printer. 
**/ 


realNumberOfPagesinDoc - DetermineNumberOfPagesinDoc 
((**thePrRecHdl).prInfo.rPage); 


if (PrJobDialog (thePrRecHdl)) 
( 
/[** 
Get the number of copies of the document that the user 
wants printed from iCopies of the TPrJob record (IM II-151). 
x f 


numberOfCopies = (**thePrRecHdl).prJob.iCopies; 


/** 
Get the first and last pages of the document that were requested to be 
printed by the user from iFstPage and iLastPage from the TPrJob record 
(IM II-151). 

**/ 


firstPage - (**thePrRecHdl).prJob.iFstPage; 
lastPage = (**thePrRecHdl).prJob.iLstPage; 


/** 
Print "all" pages in the print loop 
ax] 
(**thePrRecHdl).prJob.iFstPage = 1; 
(**thePrRecHdl).prJob.iLstPage - 9999; 
/** 
Determine the "real" number of pages contained in the document. 
Without this test, you would print 9999 pages. 
**/ 


if (realNumberOfPagesinDoc « lastPage) 
lastPage - realNumberOfPagesinDoc; 


/** 
Print the number of copies of the document 
requested by the user from the Print Job Dialog. 
**/ 
for (copies = 1; copies <= numberOfCopies; copiestt) 
( 
/** 
Install and call your "Print Status Dialog", 
kxf 


PrintingStatusDialog = GetNewDialog(257, nil, (WindowPtr) -1); 
(**thePrRecHdl).prJob.pIdleProc - checkMyPrintDialogButton; 


/** 
Restore the resource file to the printer driver's. 
x f 


UseResFile(printmgrsResFile); 
thePrPort - PrOpenDoc(thePrRecHdl, nil, nil); 





#161: When to Call, PrOpen and PrClose 6 of 8 


if (PrEfror() == noErr) 


{ 


{** 
Print the range of pages of the document 
requested by the user from the Print Job Dialog. 
we f 
pageNumber = firstPage; 
while (pageNumber <= lastPage && PrError() == noErr) 
{ 
PrOpenPage(thePrPort, nil); 


if (PrError() == noErr) 

{ 

/** 
rPage (IM II-150) is the printable area for the 
currently selected printer. By passing the current port 
to the draw routine, enables your app to use the same 
routine to draw to the screen and the printer's 
GrafPort. 

anf 

DrawStuff ((**thePrRecHdl) .prInfo.rPage, 

(GrafPtr) thePrPort, pageNumber); 


PrClosePage (thePrPort); 
pageNumber++; 
| /** End pageNumber loop **/ 
} 
PrCloseDoc (thePrPort) ; 
) /** End copies loop **/ 


/** 
The printing job is being canceled by the request of the user from the 
Print Style Dialog or the Print Job Dialog. PrError will be set to 
PrAbort to tell the Print Manager to abort the current printing job. 
**/ 
else 
PrSetError (iPrAbort); /** cancel from the job dialog **/ 
) 
else 
PrSetError (iPrAbort); /** cancel from the style dialog **/ 


if (((**thePrRecHdl).prJob.bJDocLoop == bSpoolLoop) && (PrError() == noErr)) 
PrPicFile(thePrRecHdl, nil, nil, nil, &theStatus); 


/** 


Grab the printing error before you close the Print Manager and the error disappears. 
**/ 


PrintError - PrError(); 


PrClose(); 


{xx 
You do not want to report any printing errors until you have fallen through 
the printing loop. This will make sure that ALL of the Print Manager's open 
calls have their corresponding close calls, thereby enabling the Print Manager 


to close properly and that all temporary memory allocations are released. 
**/ 
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if (PrintError !- noErr) 
PostPrintingErrors (PrintError); 


} 


if (thePrRecHdl != nil) 
DisposHandle { (Handle) thePrRecHdl); 


= if (PrintingStatusDialog != nil) 
DisposDialog(PrintingStatusDialog); 


SetPort (oldPort); 
) /** PrintStuff **/ 
Further Reference: 


* Inside Macintosh, Volume 1I-145, The Printing Manager 
* Technical Note #118, How to Check and Handle Printing Errors 
* Technical Note #122, Device-Independent Printing 
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#184: Notification Manager 


Revised by: Rich Collyer October 1989 
Written by: Darin Adler April 1988 


This Technical Note describes the Notification Manager, the part of the operating system that lets 
an application, desk accessory, or driver alert the user. 

Changes since June 1989: Made minor changes to the code examples and clarified the 
descriptions of what is needed when. 





The Notification Manager, in System Software version 6.0 and later, provides the user with an 
asynchronous "notification" service. The Notification Manager is especially useful for background 
applications; the PrintMonitor application and the system alarm (set by the Alarm Clock desk 
accessory) both use its services. 


Each application, desk accessory, or device driver can queue any number of notifications. For this 
reason, you should try to avoid posting multiple notifications since each one will be presented 
separately to the user (i.e., “you have mail,” “you have mail,” etc.). 


The Notification Manager queue contains information describing each notification request; you 
supply a pointer to a queue element describing the type of notification you desire. The Notification 
Manager queue is a standard Macintosh queue, as described in the Operating System Utilities 
chapter of Inside Macintosh, Volume II-367. Each entry in the Notification Manager queue has the 
following structure: 


TYPE NMRec - RECORD 


qLink: QElemPtr; (next queue entry) 
qType: INTEGER; (queue type -- ORDinmType) = 8) 
nmFlags: INTEGER; (reserved) 
nmPrivate: LONGINT; (reserved) 
nmReserved: INTEGER; (reserved) 
nmMark: INTEGER; (item to mark in Apple menu) 
nmSIcon: Handle; (handle to small icon) 
nmSound: Handle; (handle to sound record) 
nmStr: StringPtr; (string to appear in alert) 
nmResp: ProcPtr; (pointer to response routine) 
nmRefCon; LONGINT; {for application use} 

END; 


To use the Notification Manager, you must also use SysEnvirons (discussed in Inside 
Macintosh, Volume V and Technical Note #129) to test the System Software version. If the 
System Software is not current and the Notification Manager routines are not present, display an 
alert to inform the user that your application requires System Software version 6.0 or newer, then 
exit. 
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Using the Notification Manager 
Your program can request three types of notification: 


* polite notification: a small icon that periodically appears in rotation with the Apple 
in the menu bar; 

* audible notification: a sound to be played by the Sound Manager; 

* alert notification: an dialog box containing a short message. 


In addition, you can place a diamond mark next to the name of the requesting desk accessory or 
application in the Apple menu. 


After you have notified the user as you feel necessary (placed a diamond mark in the Apple menu, 
added a small icon to the list of icons which rotate with the Apple in the menu bar, played a sound, 
and presented the user with a dialog box to acknowledge), you should call a response procedure. 


How the Notification Manager Handles Notifications 


When the Notification Manager handles a notification, it does one or more of the following (in this 
order): 


* puts a diamond mark next to the requesting application or desk accessory in the 
Apple menu 

adds a small icon to the list of icons which rotate with the Apple in the menu bar 
plays a specified sound 

presents a dialog box for the user to acknowledge and dismiss 

calls the response procedure 


* 9 9 o 


At this point, the diamond mark in the Apple menu and the icon rotating with the Apple in the menu 
bar remain until your application removes the notification request from the queue. The Notification 
Manager only presents the sound and dialog box once. 


Creating a Notification Request 


To create a notification request, you must set up an NMRec with all the information about the 
notification you want: 


nmMark contains 0 to not place a mark in the Apple menu, 1 to mark the current 
application, or the re£Num of a desk accessory to mark that desk accessory. 
An application should pass 1, a desk accessory should pass its own refNum, 
and a VBL task should pass O. 


nmSIcon contains NIL for no icon in the menu bar, or a handle to a small icon to rotate 
with the Apple. (A small icon is a 16 x 16 bitmap, often stored in an ' SICN' 
resource.) This handle does not need to be locked, but it must be 
non-purgeable. 


nmSound contains NIL to use no sound, —1 to use the system beep sound, or a handle 
to a sound record which can be played with SndPlay. This handle does 
not need to be locked, but it must be non-purgeable. 


nmStr contains NIL for no alert, or a pointer to the string to appear in the alert. 
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nmResp contains NIL for no response procedure, —1 for a predefined procedure that 
removes the request immediately after it is completed, or a pointer to a 
procedure which takes one parameter, a pointer to your queue element. For 
example, the following is how you would declare it if it were named 
MyResponse: 


PROCEDURE MyResponse (nmReqPtr: QElemPtr); 
pascal void MyResponse (QElemPtr nmRegPtr); 


Note that when the Notification Manager calls your response procedure, it does not set up A5 and 
low-memory globals for you. If you need to access your application's globals, you should save 
your application's A5 in the nmRefCon field as discussed later in this Note. 


Response procedures should never draw or do “user interface" things. You should wait until the 
user brings the application or desk accessory to the front before responding to the user. Some 
good ways to use the response procedure are to dequeue and deallocate your Notification Manager 
queue element or to set an application global (being careful about A5), so the application knows 
when the user receives the notification. 


You should probably use an nmResp of —1 with audible and alert notifications to remove the 
notification as soon as the sound has finished or the user has dismissed the dialog. You should not 
use an nmResp of —1 with an nmMark or an nmSIcon, because the Notification Manager would 
remove the diamond mark or small icon before the user could see it. Note that an nmResp of -1 
does not deallocate the memory block containing the queue element, it only removes it from the 
notification queue. 


You can also use nmRefCon; one convenient use is putting your application's A5 in this field so 
the response procedure can access application globals. For more information about this technique, 
refer to the section about VBL tasks in Technical Note #180. 


Notification Manager Routines 


The system automatically initializes the Notification Manager when it boots. To add a notification 
request to the notification queue, call NMInstall. When your application no longer wants a 
notification to continue, it can remove the request by calling NMRemove. Neither _NMInstall 
nor NMRemove move or purge memory, and you can call either of them from completion routines 
or interrupt handlers, as well as from the main body of an application and the response procedure 
of a notification request. 


FUNCTION NMInstall (nmReqPtr: QElemPtr) : OSErr; 


Trap macro .NMInstall (SAOSE) 
On entry AO: theNMRec (pointer) 
On exit DO: result code (word) 


— NMInstall adds the notification request specified by nmReqPtr to the notification queue and 
returns one of the following result codes: 


Result codes noErr No error 
nmTypErr (-299) qType field is not ORD(nmType) 
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FUNCTION NMRemove (nmReqPtr: OElemPEr) : OSErr; 


Trap macro .NMRemove ($A05F) 
On entry A0: theNMRec (pointer) 
On exit DO: result code (word) 


. NMRemove removes the notification identified by nmReqPtr from the notification queue and 
returns one of the following result codes: 


Result codes noErr No error 
qErr Not in queue 
nmTypErr (-299) aType field is not ORD(nmType) 


How to Call NMInstall and NMRemove 


If you do not yet have glue for NMInstall and _NMRemove, you can use the following from 
MPW (these are in the include files for MPW 3.0): 


Pascal 


FUNCTION NMInstall (nmReqPtr: OElemPtr) : OSErr; 
INLINE $205F, SAOSE, $3E80; 


FUNCTION NMRemove (nmReqPtr: QElemPtr) : OSErr; 
INLINE $205F, $AO05F, $3EBO: 


pascal OSErr NMInstall (QElemPtr nmReqPtr) 
= (0x205F, OxAOSE, 0x3E80}; 


Pascal OSErr NMRemove (QElemPtr nmReqPtr) 
= (0x205F, OxAO5F, Ox3EB80); 


Also note that qType must be set to ORD (nmType), which is 8. 
The following short code segments demonstrate the use of the Notification Manager in MPW C: 


#include «OSUtils.h» 
#include «Notification.h» 


struct NMRec  myNote; /* declare your NMRec */ 
Handle ManDoneS; /* declare a handle for the sound */ 
OSErr err; /* declare for err handling */ 
myNote.qType - nmType; /* queue type -- nmType = 8 */ 
myNote.nmMark = 1; /* get mark in Apple menu */ 
myNote.nmSIcon = nil; /* no flashing Icon */ 


/* get the sound you want out of your resources */ 
ManDoneS - GetResource('snd ', soundID); 


myNote.nmSound = ManDoneS; /* set the sound to be played 


myNote.nmStr - nil; /* no alert box */ 
myNote.nmResp - nil; /* no response procedure */ 
myNote.nmRefCon = nil; /* set to nil since I don't need my A5*/ 


u————ÓÁ———————— MG 
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Before calling NMInstall, you need to see if your application is running in the background. If 
your application is in the foreground, you really do not need to notify the user, but if your 
application is in the background, you should make the following call to install the notification 
event: 


err - NMInstall ((QElemPtr) &myNote); 


Before continuing, you should handle any errors. If your application is running in the 
background, you should wait until it switches to the foreground before proceeding with anything 
else. While you are waiting for a resume event, you should take care of other events, such as 
updates. You want to make sure that when you are switched back into the foreground you remove 
the notification, and the following code does just that: 


err - NMRemove ((QElemPtr) &myNote); 


Once again, you should be sure to handle any errors. 


Further Reference: 
* Inside Macintosh, Volume II-367, V-591, The Operating System Utilities 


* Technical Note 4129, SysEnvirons: System 6.0 and Beyond 
* Technical Note #180, MultiFinder Miscellanea 
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#193: So Many Bitmaps, So Little Time 


Revised by: Rich Collyer October 1989 
Written by: Rick Blair April 1988 


This Technical Note discusses the routine BitMapToRegion, which converts a bitmap to a 
region, and is available in the 32-Bit QuickDraw INIT and from Apple Software Licensing. 
Changes since June 1989: Changed references of BitMapRgn to BitMapToRegion to 
match the updated MPW and 32-Bit QuickDraw usage, added the trap number, and documented 
how and when to use the 32-Bit QuickDraw version versus the object file version. 





The following routine is now available to convert a bitmap to a region: 
FUNCTION BitMapToRegion (region:RgnHandle; bMap:BitMap): OSErr; 

in C: 

pascal OSErr BitMapToRegion(RgnHandle region, BitMap bMap); 


The region will be built so that all one bits in bMap are inside the region and all zero bits are 
outside of it. 


AS with all QuickDraw calls which change a region, BitMapToRegion requires you to pass an 
existing region (originally created by NewRgn). If the region cannot be built due to an 
insufficient heap space or a size greater than 32K, then the routine will return an appropriate error 
code and the region will be empty. If the region would have exceeded 32K, the error will be 
rgnTooBigErr (-500). 


This function is useful for a number of situations where you have (or can produce) a bitmap 
representing an area. You can use CalcMask to produce such a bitmap. Once you have a 
region, you can perform region operations (i.e., _PtiInRgn, UnionRgn,or InsetRgn)or 
call DragGrayRgn, for example. 


This call is part of the 32-Bit QuickDraw INIT ($A8D7). If you do not wish to depend on 32-Bit 
QuickDraw, then you can obtain a version of BitMapToRegion in MPW object format which 
can be linked into an MPW program, by contacting Apple Software Licensing: 


Apple Software Licensing 

Apple Computer, Inc., 

20525 Mariani Avenue, M/S 38-I 
Cupertino, CA, 95014 

(408) 974-4667 

AppleLink: SW.LICENSE 
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If you licensed the older version of this routine, BitMapRgn, contact Software Licensing about 
receiving an updated version. We recommend you update your application to use the new version 
as soon as possible. 


The new version is now named BitMapToRegion to be consistent with the version in 32-Bit 
QuickDraw and the MPW interfaces. In addition, BitMapToRegion offers new features. You 
can now pass a one-bit pixelmap which has been coerced to a bitmap. If you pass a pixelmap 
which is too large, then you will get a pixmapTooDeepErr (-148) error. You can also pass the 
portBits of a window, much like you would do with a call to CopyBits. 


There is a potential problem with this routine, since MPW 3.1 include files contain information 
about 32-Bit QuickDraw. If you want Bit MapToRegion to be available on all machines, then 
you must use the object file from Software Licensing. The problem is that when you compile your 
application with MPW 3.1 or later, the 32-Bit QuickDraw version gets preference over the object 
file. You must comment out the routine in the include files if you want to use the object file. If 
you only care about using BitMapToRegion on machines running 32-Bit QuickDraw, then you 
need not do anything. 
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#196: 'CDEF' Parameters and Bugs 


Revised by: David Shayer October 1989 
Written by: Mark Bennett August 1988 


This Technical Note describes known bugs in the Control Manager which affect control definition 
functions (' CDEF ' resources). 

Changes since August 1988: Updated to reflect known bugs in the posCnt1 and 
thumbCntl messages and the Control Manager TrackControl call. 





The Control Manager chapter of Inside Macintosh, Volume 1-309, describes how to write a control 
definition function (' CDEF ' resource). This Note assumes a basic understanding of this chapter, 
specifically of the various messages which are sent in the message parameter. 


drawCntl (0) and autoTrack (8) 


When a ' CDEF' is called with either the message drawCnt 1 or autoTrack, it is possible for 
the high word of the param parameter to contain undefined data which could result in the failure of 
routines that rely upon all 32 bits of param being defined. 'CDEF' resources should only 
consider the low word of the param parameter when dealing with the drawCnt1 and 
autoTrack messages. 


posCntl (5) and thumbCntl (6) 


According to Inside Macintosh, the Control Manager calls a ' CDEF ' with the posCnt1 message 
and the thumbCnt 1 message if an application does custom dragging of an indicator (a thumb), 
but not if it does default dragging. This is not true. The Control Manager calls a ' CDEF ' with the 
posCnt 1 message if an application does default dragging, which is exactly the opposite of the 
way it is documented. The ' CDEF ' receives the thumbCnt 1 message regardless of which type 
of dragging an application does, however, the results are used only for default dragging (they are 
ignored for custom dragging). 


_TrackControl 


When a user clicks on your control, you normally call. TrackControl, which is supposed to 
return zero if the user does not change the control's setting or the part code if the user does change 
the setting. For ' CDEF' resources that implement custom dragging, TrackControl returns 
zero whether or not the user changes the control's setting. To work around this problem, you must 
use another method to find out if the user has changed the control's setting, such as comparing the 
control 's value before and after the call to TrackControl. 


Further Reference: 


* Inside Macintosh, Volume 1-309, The Control Manager 


un 
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#206: Space Aliens Ate My Mouse. 
-~ (ADB-The Untold Story) 


Revised by: Cameron Birse October 1989 
Written by: (Cameron Birse August 1988 


This Technical Note explains how the Apple Desktop Bus (ADB) works on the Macintosh. This 
Note covers the boot process, driver installation, use of ADB Manager calls, and answers 
commonly asked questions. 

Changes since August 1989: Added an additional vendor for ADB cables. 





Boot Process 


During the boot process, the ADB Manager finds all the devices on the bus and resolves any 
address conflicts. An address conflict is defined as two or more devices with the same original 
(default) address. A good example of this conflict is a mouse and a graphics tablet that are both at 
address 3 (relative device). The ADB Manager resolves these address conflicts as described in 
Appendix B of the ADB Specification (Apple Drawing #062-0267-E) and the Q & A section of this 
document. 


After the address resolution, the devices which have been “moved” due to address conflicts are 
now addressed, starting from the highest unused soft address and working down. The system 
now loads and executes all the resources of type ' ADBS' that match the devices on the bus (by 
original address). 


Once all the ADB service routines are installed, the ADB transceiver (microcontroller) chip starts 
polling the active device. The active device is defined as the last device to send data. Since the 
mouse (pointing device) is the most likely device to have data ready at any given time, it defaults as 
the active device after startup. 


The transceiver polls the active device (approximately every 11 milliseconds), with a Talk RO 
command. If the active device has new data, it can respond with it, and if it does not, it just times 
out. If any other devices have data to send, they can assert SRQ (refer to Figure 5 of the ADB 
Specification) at the end of the talk RO command. When the host detects an SRQ, it begins polling 
all addresses with a talk RO command until one returns data. That device then becomes the active 
device. 
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Devices have no way of knowing if they are the "active device". The algorithm for a device with 
data ready to send is as follows: 


* Wait for a talk RO command (this happens every 10 milliseconds). 

e If the Talk RO is for you, then return the data. 

* If the Talk RO is not for you, wait for the end of the command, and assert SRQ. 
e If the Talk RO is addressed to you, then respond with your data. 


Now that a device has been polled, the host retrieves the data from the bus and calls the service 
routine installed for that device (service routines are installed by calling Set ADBInfo and are 
maintained by the ADB Manager). The system passes pointers to the service routine itself, its data 
area, and the data received from the device, as well as the ADB command byte that caused the 
routine to be called. 


Normally, the service routine does not need to use the ADBOp call to retrieve data. The ADB 
"philosophy" assumes that register zero of a device is the main data transmission register. Since 
register zero is automatically polled by the system, there should be no need to call ADBOp from 
the service routine. Typically, ADBOp is used to set modes of a device, or to interrogate the 
device for status—the sort of things that should not need to be done more than once or twice during 
normal operation. 


It is important to note that ADB service routines are called at interrupt time, which means that they 
must follow all the rules regarding code that executes at interrupt time. (See Inside Macintosh 
references to VBL tasks and Device Manager I/O completion routines.) 


Installing an ADB Service Routine and Optional Data Area 


* Using the ' ADBS' resource mechanism. At boot time the system searches for 
' ADBS ' resources in the System file. The system matches desktop bus devices by 
their original address to an ' ADBS ' resource (i.e., if the machine has a device that 


responds at address 4, the system looks for an 'ADBS' resource with ID=4). 
When the system finds these resources, it loads and executes them. The limitation 
of this method is that there can only be one ' ADBS' resource for each address on 
the bus. 


A typical ' ADBS' resource allocates space in the system heap for its service routine 
and, optional, data area. Next, it moves the service routine into the allocated space 
and initializes the data area, if necessary. This code should also install an 
 ADBReInit preprocessing routine to deallocate the memory used by the service 
routine (/nside Macintosh V -367). 


When the system loads and executes an 'ADBS ' resource, it passes the following 
parameters: 


AO = Address of 'ADBS ' resource in memory. 

DO =ADB device address (0-15). This address may be different than the “original 
address," since it occurs after address resolution. 

D1 = ADB Device Type (same as the handler ID) 


With this information, the ' ADBS' code can call Set ADBInf£o to install the 


service routine and data area. The installer should make sure the handler ID 
(Device Type) is the one it expects. 
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* Install the service routine and data area usir g an ' INIT' resource. This method 
works the same as an ' ADBS' resource, except you are not passed the parameters 
in AO, DO, and D1, so you at least need to interrogate the ADB Manager (using 
. Get IndADB) to get the information. Remember to lock yourself down. 


* Use the ' INIT' resource method from within an application. 


Answers to Commonly-Asked ADB Questions 


Question: 


Answer: 


Ouestion: 


Answer: 


I need information on developing an Apple Desktop Bus product. 
Apple's Desktop Bus and ADB Device Specifications are a licensable product 
available through Software Licensing. For more information, contact: 


Apple Software Licensing 

Apple Computer, Inc., 

20525 Mariani Avenue, M/S 38-I 
Cupertino, CA, 95014 

(408) 974-4667 

AppleLink: SW.LICENSE 


Additional ADB references are as follows: 


Macintosh 
Inside Macintosh, Volume V, The Apple Desktop Bus 
Macintosh Family Hardware Reference 


Apple II 
Apple IIgs Hardware Reference Manual 


Desktop Bus 
Apple IIgs Firmware Reference Manual 


General 
Baum, Peter. “Boarding the Bus," MacUser, July 1987, p. 142. 
“An Overview of Apple Desktop Bus,” 
Call A.P.P.L.E., June 1987, p. 24. 


I would like to extend the keyboard cable for my Macintosh. How can I do this, and 
how can I make the extension? 

The ADB specification states the maximum length of all cables on the Desktop Bus is 
five meters. If you wish to use longer cables than those supplied with the ADB 
device, Kensington MicroWare (800) 535-4242, Monster Cable (800) 331-3755, and 
Data Spec (800) 431-8124 all supply them. 


Disclaimer: This listing for Kensington MicroWare, Monster Cable, and Data 
Spec neither implies nor constitutes an endorsement by Apple 
Computer, Inc. If your company supplies these cables and you 
would like to be listed, contact us at the address in Technical Note #0. 
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Question: 
Answer: 


Question: 


Answer: 


How can I use the LEDs on the Apple Extended Keyboard? 

Using the LEDs on the extended keyboard involves the . ADBOp call. Once you 
determine that you have an extended keyboard (with . CountADBs and 
Es S DE), then register 2 of the extended keyboard has the LED toggles in the 
ow 3 bits. 


Therefore, you would do a Talk to register 2 to have the device send you the contents 
of register 2, manipulate the low three bits to set the LEDs, and then pass the 
modified register 2 back to the device with a Listen to register 2 command. 


The Apple Extended Keyboard has an ID of 02 and a device handler ID of 02, while 
the Apple Standard Keyboard has an ID of 02 and a device handler ID of 01. 


Note: Atthis point it is not clear what Apple has in mind for these LEDs, so you are 
using them at your own risk. 


I am confused about the service routines and data areas passed in the . ADBOp call. 
What does it all mean? 
That 's a good question. 


FUNCTION ADBOp (data:Ptr; compRout:ProcPtr; buffer:Ptr; 


commandNum:INTEGER) : oserr; 

data is a pointer to the “optional data area". This area is provided for 
the use of the service routine (if needed). 

compRout is a pointer to the completion or service routine to be called when 


the ADBOp command has been completed. It has the same 
meaning as the service routine passed tothe Set ADBInfo call. 
buffer is a pointer to a Pascal string, which may contain zero to eight 
bytes of information. These are the two to eight bytes that a 
particular register of an ADB device is capable of sending and 
receiving. 
commandNum is an integer that describes the command to be sent over the bus. 


There is some confusion over the way that the completion routines are called from 
. ADBOp. This calling may be done in one of the following three ways: 


* You do not wish to have a completion routine called, as in a Listen command. 
Pass a NIL pointer to ADBOp. 

* You wish to call the routine already in use by the system for that address (as 
installed by SetADBInfo). Call Get ADBInfo before calling . ADBOp, and 
pass the routine pointer returned by Get ADBInfoto ADBOp. 

* You wish to provide your own completion routine and data area for the | ADBOp 
call. In this case, simply pass your own pointers to the _ADBOp call. 


a 
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Question: 
Answer: 


Question: 


Answer: 


Remember, there should rarely be a reascn to call ADBOp. Most cases are handled 
by the system's polling and service request mechanism. In the cases where it is 
necessary to call ADBOp, it should not be done in a polling fashion, but as a 
mechanism of telling the device something (i.e., change modes, or in the case of our 
extended keyboard, turn on or off an LED). 


How can I make my Macintosh II or IIx power up automatically after a power outage? 
The Macintosh II and IIx power can be turned on via the keyboard through the Apple 
Desktop Bus port (ADB) since the reset key is wired to pin two of the ADB 
connector. When you press this key, it pulls pin two to ground and initiates a 
power-on sequence. You can emulate this feature with a momentary switch 
connected to the ADB port. Note that the switch on the back panel of a Macintosh 
IIcx can be locked in the On position to automatically restart after a power outage 


An idea for a power-on circuit would be to have a momentary (one-shot) relay 
powered by the same outlet that powers the machine and have the contacts close pin 
two of the ADB connector. (Without having tried this, I am concerned that you may 
need a delay before the relay fires to give the AC time to stabilize, etc.) 


I'm more than a little confused about the way ADB device address conflicts are 
resolved at boot time. Can you enlighten me with your infinite wisdom, Cameron? 
The method used by the host to separate and identify the devices at boot time is not 
well documented, so I'll try to describe it with some clarity. 


The host issues a Talk R3 command to an address. Let's say there are two devices at 
that address. Both try to respond to the command, and when they try to put the 
random number (the address field of register 3) on the bus, one of them should detect 
acollision. The one that detects the collision backs off and marks itself (internally) as 
unmovable. 


The device that did respond successfully is then told to move to a new address (the 
highest free address). By definition, moving to a new address means that it now 
responds only to commands addressed to this new address, and it ignores commands 
to the original address. 


The host then issues another Talk R3 command to the original address. This time the 
second device responds without detecting a collision. When it successfully completes 
a Talk R3 response, it marks itself as movable. It then is told to move to a new 
address. 


The host again issues a Talk R3 command to the original address. Since there are no 
more devices at that address, the bus times out, and the host moves the last device 
back to the original address. 


At this point, the host moves up to the next address that has a device and begins the 
process all over. 


Generally, when having trouble separating devices on the ADB, it is because the 
collision detection doesn't work well. In fact, this problem is evident on Apple 
keyboards. The bug is that the random number returned in R3 isn't really a random 
number. Since the microcontrollers on the keyboards are clocked with a crystal, they 
tend to generate the same "random" number, so when the system attempts to separate 
them with a Talk R3 command, they never detect the collision. 
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One possible solution is to use a low-tolerance capacitor on the reset line of the 
microcontroller, thereby forcing the time from power on to the time reset is negated to 
be fairly random. In this way, the microcontroller can start a count until it receives 
the first Talk R3 command, and hopefully it is a different number than another device 
at the same address on the bus. 


If you find your device shows up at all addresses, it may be because it is responding 
to the move address command when it should be marked as unmovable. 


Finally, if the device doesn't show up at all, it may be because it is unable to respond 
to the Talk R3 command at boot time (i.e., not able to initialize itself and start 
watching the bus in time). 


Further Reference: 


Inside Macintosh, Volume V-361, Apple Desktop Bus 
Macintosh Family Hardware Reference, Chapters 11 & 19 
Technical Note #160, Key Mapping 

MacDTS Sample Code #17, TbltDrvr 


CO eee LLL 
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#221: NuBus Interrupt Latency 
(I Was a Teenage DMA Junkie) 


Revised by: Cameron Birse October 1989 
Written by: Cameron Birse, Mark Baumwell, & Rich Collyer December 1988 


This Technical Note discusses NuBus™ interrupt latency, and why, contrary to popular belief, the 
Macintosh is not a real-time machine. 
Changes since December 1988; Changed sample code to defer cursor rendering to a deferred 
task rather than a “pseudo- VBL” task. 





The Macintosh is not a real-time machine. The Macintosh does not support DMA. There are 
many variables in the Macintosh that make it impossible to deterministically figure out exactly when 
things are going to happen. Despite these facts, there are those who must push the envelope. For 
these courageous adventurers, we provide the following information in the hope that it speeds your 
journey. 


According to empirical evidence gathered by Apple engineering, typical NuBus to Macintosh 
transaction times fall in the 800 nanosecond to 1 microsecond range. Although the NuBus 
specification points to faster accesses, you should consider these times realistic since there is 
always some overhead. Synchronizing the NuBus and Macintosh clocks, for example, can cost a 
NuBus cycle. 


One technique that can help optimize NuBus transfers is implementing bus locking. The bus can 
be locked for a small set of transactions (we recommend a maximum of four transfers), then 
unlocked for rearbitration. In order to allow fairness, it is important to lock the bus for as short a 
time as possible. 


All processor interrupts and slot interrupts may be held off for various amounts of time by different 
parts of the system, so you must never count on instant interrupt response. To help deal with these 
delays, you should consider your data rate and include ample buffering on your card for your data. 
The following are just a few of the many system variables which affect interrupt latency: 


¢ Floppy disk accesses turn off interrupts for "significant" (read milliseconds) 
amounts of time. For instance, some disk accesses (i.e., block reads) can disable 
interrupts for as much as 15 milliseconds. Inserting a blank floppy disk turns off 
interrupts for up to 25 milliseconds. 

* Formatting a floppy disk turns off interrupts for up to 300 milliseconds. 

e LocalTalk accesses can disable interrupts for up to 22 milliseconds. 

* Assuming your interrupt handler is going to want to access your card immediately, 
there is also the arbitration for mastership of the bus, which could be in use at the 
time, and in the worst case, lock the bus, keeping you from accessing your card. 

¢ All slot interrupts, including slot VBL interrupts, hold off other slot interrupts. 
This means another card's interrupt routine (installed via SIntInstall)ora 
slot VBL interrupt routine (installed via SlotVInstall)runs to completion 
with interrupts of the slot level and below disabled. VBL tasks may be of varying 
length, since applications, as well as drivers, can and do, install VBL tasks. 
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¢ Cursor updating (performed during slot VBL time) time ranges from around 700 
Sec - 900 uSec for one-bit to eight-bit depth. Since this is done at slot VBL time, 
it holds off all other slot interrupts until it is finished. 


Warning: The performance figures cited in this Note are based on current 
Macintosh models; they are not guaranteed to remain the same in 
future machines. 


The following code lets you defer the cursor updating routine by having it run as a 
deferred task. This change means that the actual cursor rendering is performed 
with interrupts enabled, which allows the occurrence of other interrupts. It'should 
be noted that there is a slightly visible flickering of the cursor as a result of using 
this technique. 


REAR KWH KKK KKK KKK KKK RR RARR RR KERR kk ER RR KERR RT RR RR RR RA KK kkt 


kak 


AW Defer Cursor 

ee This program defers the cursor updating that normally happens 
XX during slot VBL time. Since the cursor updating can take as 
ERS long as 900MSec, and holds off other slot interrupts, it is 
Ed handy to be able to defer the updating to a more civilized time. 
kid This program replaces the normal jCrsrTask with a routine that 
xe installs the real jCrsrTask routine as a deferred task. 

Kak 

xx Build commands: 

ok 

NUN asm DeferCrsr.a -lo DeferCrsr.a.lst -1 

eae link DeferCrsr.a.o -o DeferCrsr 


WW KKK KKK KKK KKK RR RR KERR Ok OR OK MR ARE ER TER RR RR RR RR KERK EEK K KKH KKK 


STRING ASIS 

PRINT OFF 
INCLUDE 'Traps.a' 
INCLUDE 'SysEqu.a' 
PRINT ON 


fe ce he ede he e oe ede de ce e ee e oe ce RR coke kc oe cec ee e x Entry RARR ERK RR RR RR RR RR RR RA RR N MRT 


Entry MAIN 


bra.s Entry2 


he hehehe ce II C000 M tee e le ede een deinde e MyDefTask * RARR RR RT TR TR RR RR RA RR de RR RA 


TaskBegin 
MyDefTask 
DC.L 0 ;qLink (handled by OS) 
DC.W 0 iqType (equ 7, find this value in MPW AIncludes) 
DC.W 0 #dtFlags (reserved, don't mess with 'em) 
DC.L 0 ;dtAddr (pointer to actual routine to be performed) 
DC.L 0 sdtParm (optional parameter, this example doesn't use it) 
DC.L Q ;jdtReserved (should be zero, DC.L 0 takes care of that) 
SysCrsrTask 
DC.L 0 
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KKK KR REN KKK KEKE KEKE KKK My jCrsrTask KKK KEK RR eec ee KR RR RR RR RR RA 


MyjCrsrTask 
movem, l a0/d0,- (sp) 
lea MyDefTask,a0 ¿point to our deferred task element 
move.l SysCrsrTask,dtAddr (a0) ;set up pointer to routine 
move.w #dtOType, dt Type (a0) ;set queue type 
 DTInstall ;install the task 
movem, 1 (sp) *, a0/dO 
rts 
TaskEnd 


kekki kkk kkk kkk kk kk k k k k k Entry2 AK oce hee ede de cec oe ehe dec oc kc kc coke oe e ene kkk 


TaskSize EQU TaskEnd-TaskBegin 
Entry2 
move,l $TaskSize,dO ;TaskSize = Deferred task element, room for 


; a pointer (to original jCrsrTask), and 
zour jCrsrTask 


_NewPtr , SYS, CLEAR imake a block in the system heap 
bne.s Abort ;no room at the Inn, head for the manger 
move.l a0,a2 ¿got a good pointer, keep a copy 
move.l a0,al ;a0 = source, al = destination for 
; BlockMove 
lea MyDEFTask, a0 ;copy the task, etc. into the system heap 
move.w #TaskSize,d0 
. BlockMove 
lea dtQElSize(a2),a0 ;move original jCrsrTask pointer into our 
move.1 jCrsrTask, (a0) ; pointer holder 
lea dtOElSize*4(a2),a0 ;replace jCrsrTask pointer with a pointer 
move,.l a0, jCrsrTask ; to our jCrsrTask 
abort rts ;all's well that ends... 
END 


* Note, as an aside, that while using MacsBug, interrupts are disabled. 


In summary, you cannot depend on real-time performance when transferring data between NuBus 
and the Macintosh. It is important to provide sufficient buffering on the card to allow for the 
variance in interrupt latency. Driver calls can be used to determine the amount of data available to 
be transferred, and transfers can be made on a periodic basis. 


Remember too, since the entire system is so heavily interrupt-driven, it is very unfriendly for 
anyone to disable interrupts and take over the machine for long periods of time. Doing so almost 
always results in a sluggish user interface, something which is usually not well received by the 
user. 


Further Reference: 


* 


Inside Macintosh, Volume V, The Device Manager 

Inside Macintosh, Volume V, The Vertical Retrace Manager 
Macintosh Family Hardware Reference 

* Designing Cards and Drivers for the Macintosh I and Macintosh SE 


NuBus is a trademark of Texas Instruments 
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#238: Getting a Full Pathname 


Revised by: Keith Rollin October 1989 
Written by: Keith Rollin June 1989 





This Technical Note describes how to generate a full pathname, given either a Working Directory 
ID or a real vRefNum and a DirID. By using the techniques shown in this Note, you can find the 
full pathname from information such as that returned by Standard File. 

Changes since June 89: Added a note on how to check for A/UX. Fixed bug in C version: 
BlockMove () parameters were reversed in pSt rcpy (); added range checking to pSt rCat (); 
changed references from “longint” to “long”. Fixed bug in Pascal and C versions: Changed 
fsRtDir to fsRtdirID and made references to gHaveAUX consistent. 


This Note presents two routines. The first routine is called PathNameFromwD. It takes an HFS 
Working Directory ID and returns the full pathname that corresponds to it. It does this by calling 
 PBGetWDInfo to get the vRefNum and DirID of the real directory. It then calls 
PathNameFromDirID and returns its result. 


PathNameFromDirID takes a real vRefNum and a DirID and returns the full pathname that 
corresponds to it. It does this by calling PBGetCat Info for the given directory and finding out 
its name and the DirID ofits parent. It then performs the same operation on the parent, sticking 
its name onto the beginning of the first directory. This whole process is continued until we have 
processed everything up to the root directory (identified with a Dir ID of 2). 


Warning 


This Note is being released in response to demand from developers. However, for the following 
reasons, generating full pathnames is highly discouraged: 


* Problems arise when accessing volumes that use file systems other than HFS. For 
instance, PathNameFromDirID uses a butcherous hack to be A/UX friendly. 
A/UX likes subdirectories separated by slashes in a pathname, rather than colons. 
This routine automatically uses colons or slashes as separators based on the value 
of gHaveAUX. To check for the presence of A/UX, examine bit 9 of 
HWCfgF lags. If it is set, you are running under A/UX. This global must be 
initialized correctly for this routine to do its thing. However, because of this 
dependency on the idiosyncrasies of file systems, generating full pathnames for 
other than display purposes is discouraged; it changed in the past when A/UX 
was implemented, and it may change again in the future to support other file 
systems such as ProDOS, MS-DOS, or OS/2. 


* One reason developers have stated for needing to know the full pathname for is so 
that they can remember the location of a particular file. Saving a file’s full 
pathname should only be used as a last resort. Instead, you should remember the 
DirID of the directory the file is in along with it’s name. This way, you will still 
be able to find your file even if the directory has been moved. Under System 7.0 
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or later, save the file's unique 32-bit ID number as well, so that you can also find 
the file even if it’s name has changed. 


Either of these methods may fail if a volume has been restored from a backup. In 
that case, you might be able to find the file by searching with its full pathname. If 
you find the file, note again the DirID of the directory it is in, and save it for 
future use. If running under 7.0 or later, also note the file's ID number. 


e The routines below are written to return Pascal strings (a length byte followed by 
the ASCII characters). Hence, the limit on the length of a Pascal string is 255 
characters. However, a file's full pathname may be longer than 255 characters. 
Any routine you write should be prepared for this contingency. 


* The reason why the sample routines below were written to return Pascal strings is 
because that's the way the File Manager likes them. However, as you now know, 
a file's full pathname may be longer than that acceptable to the File Manager. 
Therefore, even if you do get fancy and use things like handles and Munger to 
create a mondo-length filename, you will still have to parse it into pieces less than 
255 bytes for the File Manager to handle. Simply using a DirID is a lot easier. 


* These routines assume the existence of HFS. If you intend for your program to 
run under MFS, then you should make the appropriate checks and write special 
cases accordingly. 


MPW Pascal 


(** PathNameFromDirID te te TK HK I I RK KKK TT TOK KR I TK IH REE AIK EK IKK KKK IKKEKKK KK k k k ) 


FUNCTION PathNameFromDirID(DirID: longint; vRefNum: integer): str255; 


VAR 
Block: CInfoPBRec; 
directoryName,FullPathName: str255; 


BEGIN 

FullPathName:=''; 

WITH Block DO BEGIN 
ioNamePtr;-(directoryName; 
ioDrParID:-DirID; 

END; 


REPEAT 
WITH Block DO BEGIN 
ioVRefNum:-vRefNum; 
ioFDirindex:=-1; 
ioDrDirID:-Block.ioDrParID; 
END; 
err:=PBGetCatInfo(@Block, FALSE) ; 


IF gHaveAUX THEN BEGIN 
IF directoryName[1]«»'/' THEN BEGIN 
( If this isn't root (i.e. "/"), 
{ append a slash ('/') ) 
direct oryName:=concat (directoryName, '/'); 
END; 
END 


a ee ee 
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END; 


ELSE BEGIN 
directoryName:-concat (directoryName, ':'); 
END; 
FullPathName:-concat (directoryName,FullPathName); 
UNTIL (Block.ioDrDirID-fsRtDirID); 


PathNameFromDirID:-FullPathName; 


{** PathNameFromWD RR RR REK KERR RR RE KICK RR RR Ck ce RR RR KC Ck kk ok kk ER RR d Ck ek 0 XO IO jo c) 


FUNCTION PathNameFromWD(vRefnum: longint): str255; 


VAR 


BEGIN 


END; 


MPW C 


myBiock: WDPBRec; 


PBGetWDInfo has a bug under A/UX 1.1. If vRefNum is a real vRefNum 
and not a wdRefNum, then it returns garbage. Since A/UX has only 1 
volume (in the Macintosh sense) and only 1 root directory, this can 
occur only when a file has been selected in the root directory (/). 
So we look for this and hard code the DirID and vRefNum. ) 


IF (gHaveAUX) AND (vRefnum--1) THEN BEGIN 
PathNameFromWD:-PathNameFromDirID(2,-1):; 


END 
ELSE BEGIN 


WITH myBlock DO BEGIN 
ioNamePtr:-NIL; 
LoVRefNum:=vRefnum; 
ioWDIndex:-0; 
ioWDProcID:-0; 

END; 


( Change the Working Directory number in vRefnum into 
( a real vRefnum and DirID. The real vRefnum is 

( returned in ioVRefnum, and the real DirID is 

( returned in ioWDDirID. ) 


err:=PBGetWDInfo(@myBlock, FALSE); 
WITH myBlock DO 


PathNameFromWD:-PathNameFromDirID(ioWDDirID,ioWDVRefnum) 
END; 


/** PathNameFromDirID e e e de e c e kk RR RR ee e he ke e Dh e e he he Ok e ke e e te e he ke he ke RR e e RR e c e e e e e Ef 


char *PathNameFromDirID(DirID, vRefNum, s) 


long 
short 
char 


DirID; 
vRefNum; 


*s; 
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CInfoPBRec block; 
Str255 directoryName; 


*s = 0; 
block. dirInfo. ioNamePtr 
block.dirinfo.ioDrParID 


ll 


directoryName; 
DirID; 


do { 
block.dirInfo.ioVRefNum = vRefNum; 
block,dirInfo.ioFDirIndex - -1; 
. block.dirInfo.ioDrDirID = block.dirInfo.ioDrParID; 


err - PBGetCatInfo(&block,false); 
if (gHaveAUX) { 
if (directoryName[1] != '/') 
/* If this isn't root (i.e. '/'), append a slash ('/') */ 
pStrcat (directoryName,"\p/"); 
) else 
/* Append a Macintosh style colon (':') */ 
pStrcat (directoryName,"Xp:"); 
pStrcat (directoryName,s); 
pStrcpy (s, directoryName); 
) while (block.dirInfo.ioDrDirID != fsRtDirID); 


return(s); 


/** PathNameFromwD eI IO KERR RR RR RR KERR EER e RR RE RR RR RR RE WOW e e e RR k e ER ERK RR RR RR N e e f 


char *PathNameFromWD (vRefNum, s) 
long vRefNum; 
char *s: 


WDPBRec myBlock; 


/* 

/* PBGetWDInfo has a bug under A/UX 1.1. If vRefNum is a real vRefNum 
/* and not a wdRefNum, then it returns garbage. Since A/UX has only 1 
/* volume (in the Macintosh sense) and only 1 root directory, this can 
/* occur only when a file has been selected in the root directory (/). 
/* So we look for this and hard code the DirID and vRefNum. */ 


if (gHaveAUX && (vRefNum == -1)) 
return(PathNameFromDirID(2,-1,5s)); 


nil; 


myBlock.ioNamePtr 
myBlock.ioVRefNum vRefNum; 
myBlock.ioWDIndex 0; 

myBlock.ioWDProcID = 0; 


/* Change the Working Directory number in vRefnum into a real vRefnum */ 
/* and DirID. The real vRefnum is returned in ioVRefnum, and the real */ 
/* DirID is returned in ioWDDirID. */ 

PBGetWDInfo(&myBlock,false); 


return (PathNameFromDirID (myBlock.ioWDDiriD,myBlock.ioWDVRefNum, S)); 
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/** pStrcat / pStrCpy FIO IO KEER R RR RE RE ER RR ER RR RR ER EER ER EER ER RR RR EER RR ER REK f 


/* 


/* A couple of utility routines. C is thoughtless enough to not really 

/* support P-strings. In order to perform string copies and concatenations, 
p* these routines are provided. 

/* 


J E E He e e e Ko Ck XC RO k KERR RR ER RR e KORR ACC EK RR RE ER RR ROC KK KEER REKE ER ICICI E ae e K Kok IOI IR IK f 


#define MIN(a,b) (((a)«(b))?(a):(5b)) 


char *pStrcat(dest, src) 

unsigned char *dest, *src; 

{ 
long sLen = MIN(*src, 255 - *dest); 
BlockMove(src + 1, dest + *dest + 1, sLen); 
*dest += sLen; 
return (dest); 


char *pStrcpy(dest, src) 
unsigned char *dest, *src; 


( 
BlockMove(src, dest, (long) *src + 1); 


return (dest); 


Further Reference: 


e Inside Macintosh, Volume IV-89, File Manager 


EE —MM——————————————————— 
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#244: A Leading Cause of Color Cursor Cursing 


Revised by: Alan Mimms October 1989 
Written by: Alan Mimms June 1989 


Working with color cursors you create from scratch can cause headaches. This Technical Note 
may help a bit. 
Changes since June 1989: Added a warning about purgeable 'clut' resources. 





If you're building an application that creates color cursors, you may encounter some quirks present 
in Color QuickDraw that manifest themselves in hard-to-understand ways. 


If your cursor is, say, 15 pixels tall and 9 pixels wide, you might be tempted to use these values 
for the bounds .bottom and bounds . right, respectively, in your cursor's pixel map. 
Don't. The problem is that when the cursor's image needs to be expanded (i.e., when you 
specify a two bit-per-pixel cursor and the mouse pointer is on an eight-bit screen) the 
. SetCCursor trap rounds the width of the pixel map in such a way that you'll get only the space 
required for a 15 by 8 pixel map allocated for the expanded cursor data. When the cursor's image 
is expanded into this too-small expanded cursor data handle as a 15 by 9 pixel map, something in 
your heap will get munched. - 


The cure is simple. Make certain that you always specify that the pixmapHandle^^.bounds 
be 16 by 16. This will cause SetCCursor to properly allocate the expanded data area, and all 
will be well in the land. Since the amount of data drawn for a cursor is specified by the cursor's 
pixel values and ' c1ut' resource, trying to save a few bytes by making the bounds rectangle 
smaller than 16 by 16 wouldn't have been very helpful anyway. 


Another potential problem is with the color cursor's color table. If you load the color table from a 

'clut' resource using GetCTable, you should make sure that the 'clut' is marked 
non-purgeable while the color cursor is in use. If you do not take this precaution, bombs will 
occur if your ' clut ' gets purged at in inopportune time. 
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#247: Giving the (Desk)Hook to INITs 


Revised by: Pete Helme October 1989 
Written by: Pete Helme August 1989 


This Technical Note discusses INIT evils, the foremost of which deals with clearing DeskHook 
and DragHook at INIT time. 
Changes since August 1989: Added warning about clearing DragHook. 





If you've survived the typical DTS Tirade* and still feel the need to display a dialog box or window 
in an INIT, you need to be aware of a problem which exists on Macintoshes earlier than the 
Macintosh II (remember those?). There is a low-memory global named DeskHook ($A6C), 
which can contain a pointer to a routine responsible for painting the Macintosh desktop. If it is 
NIL, which is usually the case, the System paints the desktop with the standard pattern. 


When you start displaying dialog boxes or windows that obscure the desktop in your INIT (this is 
really hard not to do, so keep reading and don't let us catch you skipping ahead to another 
Technical Note with pictures of human genetic experiments gone sour— you know which one I'm 
talking about), the System looks at DeskHook for a desktop updating routine. Since the 
Macintosh II, the System has cleared this hook prior to calling your INIT; however, on machines 
before the Macintosh II, this hook is not cleared before the System calls your INIT, so there is 
usually some junk hex lounging about in there. Since DeskHook is not NIL, when the System 
tries to use and perform a JSR to this "address," it blows big chunks. 


So unless you like big chunks, the easy way to fix this problem is to clear DeskHook before 
doing any window drawing. The most logical time to do this is during your initialization: 


PEA thePort (A6) ; initialize own grafPort off A6 
_InitGraf 

_InitFonts 

_InitWindows 

_TEInit 

CLR.L ”- (A7) ^ 

_InitDialogs 

CLR.L  $A6C ; DeskHook 


For you high-level types, this translates into: 


procedure ClearDeskHook; 
inline 
$42B8, SOAGC; ( CLR. L $A6C ; DeskHook } 


It doesn't hurt to clear it on newer machines either, even if it is already clear (you'll just have to 
trust me on this one), so go ahead and clear it all the time. 
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Note: Some INITs might actually use DeskHook. However, the popular ones that paint CO 
a picture on the desktop, which you might think use it, do not. They use other 
methods. (We know, we checked. We have the technology.) For those of you 
who have seen a real procedure pointer in location $A6C on earlier Macintoshes, 
don’t worry. The system does not actually set DeskHook for its own use until the 
first application loads, so clearing it while INITs load is okay. 


If there is some daring INIT out there which sets DeskHook, we haven't heard 
about it. As is the case with many low-memory globals, using DeskHook has 
never been supported. 


Watch Out For This Guy Too 


It should also be noted that DragHook ($9F6) is not cleared during INIT time on early 
Macintoshes either, and it will probably contain $FFFFFFFF. I guess no one in early Macintosh 
System Software wanted DeskHook to be lonely. DragHook can contain a pointer to a 
procedure that is called continuously while the mouse button is down. If you have a user interface 
at INIT time that ultimately calls TrackGoAway for windows or TrackControl for 
controls, look out. If the control is of the type to allow one of it’s parts to be dragged with an 
outline, like a scroll bar’s thumb, it calls DragTheRgn, which checks to see if DragHook is 
NIL, and if it is not, it tries to perform a JSR to whatever address is there. TrackGoAway also 
tries to perform a JSR to that address if it's not NIL. So make sure DragHook is clear before you 
attempt to use one of these routines. 


In fact, if you've got a lot of spare time, like you're on the Voyager 7 project waiting to come into 
contact with Black Lectroids and you have an old Macintosh 512KE or Plus lying around, why not 
try randomly clearing out all low-memory globals and see what does and doesn't crash? Sure to 
be an ice breaker at parties. 
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* (Asterisk) | 

What am I yakking about? If you've ever written to DTS about getting help with displaying some 
kind of modal monster at INIT time (remember this for the later quiz kids, that's the time before 
this sort of thing should normally happen), you know of what I yak. 


We have this pet peeve with INITS that interrupt the boot process with a modal dialog box which 
asks us to enter our name then proceeds to ask us how many characters we just entered and what 
we had for dinner, especially when we've left the desk to go get a fix of a highly caffeinated 
substance. INITS were created for developers (and us) to install system patches and device drivers 
and make the occasional rude startup sound to annoy the person occupying the cube next to ours. 
INITS were not developed to ask for personal (asexual) histories. 


We do not mean to say that we don't like all graphics at boot time. The ShowINIT icon 
mechanism that was popularized by Paul Mercer is great. In fact, we encourage it's use and we 
gladly give out the ShowINIT MPW object file, with installation help, to anyone who asks for it. 
This is an excellent method for a developer to inform a user whether a ROM patch or device driver 
has been successfully installed (show the red X through the icon on the rare occasion when things 
go wrong). Of course, this doesn't work if some non-social INIT makes an InitWindows 
call, which wipes clean the entire screen (and with it all previous ShowINIT icons). You may 
argue that having the InitWindows trap wipe out the entire screen at INIT time is a bad 
Macintosh OS INIT-time design, but this is one of our biggest complaints with the whole INIT 
look-at-my-fancy-splash-screen-or-complete-my-insanely-great-modal-dialog-box phenomenon. 


If you feel the need to notify the user of an important occurrence during boot time, initialize a 
notification request with the Notification Manager in your INIT code (see Technical Note #184, 
Notification Manager, and yes, it is perfectly legal to use at INIT time), and the system will notify 
the user after the boot process, when the event mechanism starts. The now alerted user can then 
activate your desk accessory, application, or whatever and you can perform whatever kind of 
pyrotechnics you want. 


If you are going, “But, but, but..." because various Apple products are guilty of INIT evils, then 
you should realize that we are giving Apple engineers the same, if not more, grief to cleanse their 
acts as well. 


It's not that we're telling you that you cannot put up a modal dialog box at INIT time if you feel 
like it's really-absolutely-positively-it-was-your-dying-mother's last-wish-necessary. It's just that 
DTS would like to see a cleaner Macintosh interface (as I'm sure you all would), and a more 
uniform boot time appearance can help achieve this goal. 
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#248: DAs & Drivers in Need of (a Good) Time 


Revised by: Pete Helme October 1989 
Written by: Pete Helme August 1989 


This Technical Note describes a few complications which rear their rather ugly little heads when a 

desk accessory or driver needs periodic time. It also presents a few solutions to work around these 

problems and make life easier, at least periodically. 

Changes since August 1989: Corrected BitClr and BitSet examples. Okay, I admit 

it I was having too good of a time when T wrote the original Note and messed up the bit 

re doi at the end. My vision was blurred; I was in no condition to see those tiny little 
ings. 


eee LL 


See Jane’s Heap, See accRun... 


MultiFinder is our friend. Our friend, that is, until a driver or desk accessory is called when in an 
unknown heap. Then things get complicated. When a driver is called at accRun time under 
MultiFinder, one can never be exactly sure of the heap in which it will find itself. When a DA 
receives an open call, or any other messages besides accRun, under MultiFinder, the system heap 
is switched in as the current heap. [This is true unless a user “force” switched the DA into an 
application heap by holding down the Option key when opening the DA. In this particular case, the 
application’s heap will be switched in.] During the accRun cycle, whatever heap is currently 
switched in will be the driver’s heap as well, and surprise, surprise, that heap may not be the 
system heap. 


This situation could be a real problem if your DA allocates memory or creates a window during that 
accRun period. Why? What if the application whose heap the DA is in suddenly slips a bit and 
decides to call it quits before the DA? You'd be stuck with allocated blocks in a zone that suddenly 
doesn’t exist. Eventually, your DA would go belly up, and whoever bought your DA or driver 
would be on the phone to a local dealer demanding retribution. 


So what’s the solution? The easiest way out of this situation is to simply not do any memory 
allocation or display any newly created windows or dialog boxes during accRun. So what if it’s 
a cop out, it’s easy to implement. 


Being the good souls that we are in DTS, we're not going to leave you hanging there with nowhere 
to go. We prefer you heed the previous solution, but we realize that there may be rare times when 
you might need a window during accRun. We've devised a solution, albeit a bit strange, but one 
that's easy enough to use. 


The basic problem is that the DA needs to know in which heap it should be allocating it's new 


storage. It would be nice if the DA knew in which heap it was opened and could allocate the new 
stuff there, and it's easy enough to do, so here is what you need to know to do it. 
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Switching from the current heap to the "preferred" heap is fairly simple. When you feel the need to 
allocate memory or create a window during accRun, first save the current heap zone with 
_GetZone. Now, get the handle to the actual driver for the DA. You can do this by looking at 
the dCt1Driver offset of the DAs device control entry (DCE). The DCE is always in register A1 
when a control call to the DA is made. Use _Handlezone on the handle to the DAs driver to 
give you a pointer to the heap in which the driver resides. Pass that value to Set Zone. Once 
you have switched in the correct heap, do whatever memory allocation or window creation you 
need, and then make sure to set the current zone back to the saved zone with _Set Zone. 


The following short routine, borrowed, in part, from an MPW sample DA, shows one way to set 
up the correct zone. 


Pascal short DRVRControl(CntrlParam *ctlPB, DCtlPtr dctl) 
( 

extern void doCtlEvent (); 

extern void doPeriodic(); 


TH2 driverZone; 
THz savedZone; 


/* 

* The current grafPort is saved & restored by the Desk Manager 

*/ 

switch (ctlPB-»csCode) { 

case ACCEVENT: /* accEvent */ 
HLock (dCt1-»dCtlStorage); /* Lock handle since it will 
be dereferenced */ 
doCtlEÉvent( *((EventRecord **) &ct1PB->csParam{0)), 
(Globals *) (*dCtl-»dCtlStorage)); 

HUnlock (dCtl-»dCtlStorage); 


break; 
/* 
* Hey! Look here! 
wf 
case ACCRUN: /* periodicEvent */ 
savedZone - GetZone(); /* save a pointer to the current heap */ 
driverZone = HandleZone(dCtl-»dCtlDriver); /* get the heap our dríver 
resides in */ 
Set Zone (driverZone); /* use that as the current heap */ 
doPeriodic(dctl); /* go do your periodic stuff */ 
Set Zone (savedZone) ; /* restore the old heap */ 
break; 
default: 
break; 
} 
return 0; 


) 


One note of caution: Watch out for changes in the resource chain when in accRun, as it may not 
be what you expect when MultiFinder is active. 
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*Houston, We've Got a Re-Entry Problem" 


Displaying an alert or other modal dialog box is a common occurrence in Macintosh programming, 
even in DAs. But since DAs are not applications, modal dialog boxes pose other problems when 
displayed under MultiFinder. This problem is reentrancy. If your DA or driver asks for periodic 
time, it continues to receive it when it display a modal dialog box. Bummer. Your modal dialog 
routine might even be called again, and again, and again, and again, and you get the idea. This 
problem occurs because ModalDialog calls the SystemTask trap, which in turn calis 
drivers which asked for time, including yours. There is no internal check by the System for this 
possible problem, so it's up to you and your driver to be prepared. 


We realize that some DAs and drivers expect, and depend upon, this functionality. We're just 
taking this opportunity to inform the rest of you that this is a situation about which you should be 
aware. 


An easy way to avoid this issue is to simply tell the Device Manager not to call your DA when you 
display an alert or other modal dialog box. Remember that dNeedTime bit you set when you 
opened your DA so you'd get time? Just clear it before yourcallto Alert or ModalDialog. 
As long as the bit is clear, your DA does not receive any periodic time. Remember to reset it once 
you are done with your Alert or _ModalDialog trap call. 


The BitClrand BitSet Toolbox utilities are a mite on the brain-damaged side, and the bits 
are the reverse of conventional 680x0 numbering (numbering starts from the high-order bit instead 
of the low-order bit). This difference necessitates a calculation for figuring out the correct bit as 
Shown in the following example: (I think whoever wrote these Toolbox utilities did this just to see 
if anyone was paying attention.) 


Pascal 
BitClr(8dce^.dCtlFlags, 2); ( clear bit 5/dNeedTime bit. IM I-471 | 
BitSet(8dce^.dCtlFlags, 2); ( set bit 5/dNeedTime bit. IM I-471 | 


or the kind of more efficient, but less efficient than C: 


CONST 

dNeedTime - $2000; ( Bit 5 of high-order byte of word ) 

dce^.dCtlFlags ss BAND(dce^.dCtlFlags, BNOT(dNeedTime)); | clear bit 5/dNeedTime bit. ) 
dce^.dCtlFlags :- BOR(dce^.dCtlFlags, dNeedTime) ; { set bit 5/dNeedTime bit. } 
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NEL 


C 


BitClr(&dce-»dCtlFlags, 2); /* clear bit 5/dNeedTime bit. IM I-471 */ 
BitSet (&dce-»dCtlFlags, 2); /* set bit 5/dNeedTime bit. IM I-471 wf 


or the somewhat more efficient: 


#define dNeedTime 0x2000 /* Bit 5 of high-order byte of word */ 
dce->dCtlFlags &= ~dNeedTime; /* clear bit 5/dNeedTime bit. */ 
dce-»dCtlFlags |= dNeedTime; /* set bit 5/dNeedTime bit. */ 


One More Thing... 


We cannot overemphasize our viewpoint that if you are writing a DA and the result looks and acts 
more like an application, then write an application instead and save us all a lot of headaches. 


Further Reference: 


* Inside Macintosh, Volume II, The Memory Manager 


* Technical Note 4180, MultiFinder Miscellanea 
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#249: Opening the Serial Driver 


Revised by: Sriram Subramanian October 1989 
Written by: Sriram Subramanian August 1989 


This Technical Note describes the recommended, safe, and compatible way to open the Macintosh 
serial driver, and it explains why you should no longer check for port availability. 
Changes since August 1989: Corrected syntax errors in the sample code. 


EE mmama 


Starting with the 128K ROM, we recommend that applications do not check the low-memory 
globals SPConfig, PortAUse, and PortBUse before opening the serial driver. It is no longer 
the application's responsibility to test for the availability of the serial ports. When running 
AppleTalk Phase 2, it is now possible to use the printer port for asynchronous serial 
communication while AppleTalk is active and using an alternate connection, such as EtherTalk or 
TokenTalk. 


The serial driver automatically verifies that the serial port is correctly configured and free for an 
asynchronous driver; if it is not correctly configured or free, the serial driver returns either the 
result code port NotCf or portInUse. The serial driver already has all the code built into it for 
testing the availability of the serial ports before trying to complete the . Open call. Therefore, since 
all of the required checks are made inside the driver itself, we recommend that a simple 
OpenDriver call be made when you need to use a serial port. 


By using just the OpenDriver call to the serial driver, you ensure that your code is both 
user-friendly and compatible with future versions of the System Software. 


Pascal 
result := OpenDriver('.AOut',aoutRefNum); ( Check result codes in a real application. ) 
result := OpenDriver('.AIn',ainRefNum); ( See failure mechanism in Sample Code. ) 


result = OpenDriver("\p.AOut", GaoutRefNum); /* Check result codes in a real application.*/ 
result = OpenDriver("\p.AiIn", sainRefNum) ; /* See failure mechanism in Sample Code. */ 


If you must maintain compatibility with the 64K ROMS, call _SysEnvirons, then either call 
RAMSDOpen for the 64K ROM machines or OpenDriver for the others. 


Further Reference: 


* Inside Macintosh, Volume II-249, The Serial Driver 
e Inside Macintosh, Volume IV-225, The Serial Driver 

* Technical Note #129, SysEnvirons: System 6.0 and Beyond 
e DTS Q&A Stack 
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#252: Plotting Small Icons 


Revised by: James Beninghaus October 1989 
Written by: James Beninghaus & Dennis Hescox August 1989 


This Technical Note discusses the ' SICN' resource format and how to plot one in a Gra£Port. 
Changes since August 1989: Corrected errors in the Pascal code and spruced up the rest. 





Introduction 


Apple first introduced the ' SICN' resource so that the Script Manager could represent which 
country specific resources are installed in the system by displaying a small icon in the upper right 
corner of the menu bar. You can pass a ' SICN' resource to the Notification Manager or Menu 
Manager, and they will draw it for you automatically—you should continue to let them do so. 
However, if you want to draw a small icon in your application's window, then this Note can help. 


What does a ' SICN' look like? Following is a ' SICN' representation of a dogcow to help 
answer this question: 
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'SICN' FatBits 


There is reason to believe that this representation is actually a baby dogcow. Due to the protective 
nature of parent dogcows, young dogcows are rarely seen. This one was spotted during a DTS 
meeting after it drew attention to itself by crying “moo! woof!". (Note that this dogcow said “moo! 
woof!” because it was immature; adult dogcows naturally say, “Moof!”.) 
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'SICN' Resource 


A 'SICN' resource contains any number of small icon bit images. Each small icon ina ' SICN' 
list describes a 16 by 16 pixel image and requires 32 bytes of storage. Like an 'ICN#' resource, 
there is no count of the number of icons stored ina 'SICN'. The following ' SICN' resource, in 
MPW Rez format, contains two small icons: 


resource 'SICN' (1984, "clarus") ( 
( /* array: 2 elements */ 


$"00 48 O00 B4 00 B4 40 52 CO 41 AO 81 OF BE BF 18" 
$"40 18 40 18 47 88 48 48 48 48 44 44 3C 3C 00 00", 


$"00 48 00 FC 00 FC 40 7E CO 7F EO FF FF FE FF F8" 
S"7F FB 7F F8 7F FB 78 78 78 78 7C ?C 3c 3C 00 00" 


The Right Tools for the Job 


The Macintosh Toolbox interfaces do not describe all the necessary data structures needed to work 
with 'SICN' resources. As shown in the following example, defining the ' SICN' type as an 
array of 16 short integers and the handles and pointers to this array type make life much easier. 


Pascal 

TYPE 
SICN - ARRAY(O .. 15] of INTEGER; 
SICNList = ARRAY[O .. 0] of SICN; 
SICNPtr = ^SICNList; 
SICNHand - ^SICNPtr; 

C 

typedef short SICN{16); 

typedef SICN *SICNList; 


typedef SICNList *SICNHand; 


The Missing Count 
The ' SICN' resource does not provide a count to indicate the number of small icons contained 


within; however, you can easily determine this number by dividing the total size of the resource by 
the size of a single small icon. 
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Pascal 


CONST 
mySICN - 1984; 

VAR 
theSICN : SICNHand; 
theSize : LONGINT; 
theCount : LONGINT; 
theIndex : LONGINT; 


theSICN := SICNHand(GetResource('SICN', mySICN)); 
IF (theSICN «» NIL) THEN BEGIN 
theSize := GetHandleSize (Handle (theSICN)); 
theCount :- theSize DIV sizeof(SICN); 
END; 


C 


#define mySICN 1984 


SICNHand theSICN; 


long theSize; 
long theCount; 
long theIndex; 


theSICN = (SICNHand) GetResource('SICN', mySICN); 
if (theSICN) ( 
theSize = GetHandleSize((Handle)theSICN) ; 
theCount = theSize / sizeof (SICN);: 


The Plot 'SICN's 


The example procedure Plot SICN draws one small icon of a ' SICN' resource. It takes the 
handle from theSICN and the position in the list from the Index within the rectangle theRect 
of the current GrafPort. 


Following is an example call to Plot SICN which plots all the small icons in a resource into the 
same rectangle: 


Pascal 


SetRect (theRect, 0, 0, 16, 16); 
FOR theIndex := 0 TO theCount-1 DO 
PlotSICN(theRect, theSICN, theIndex); 


C 


SetRect (&theRect, 0, 0, 16, 16); 
for (theIndex = 0; theIndex < theCount ; ++theIndex) 
PlotSICN(&theRect, theSICN, theIndex); 


Because PlotSICN uses CopyBits and CopyBits can move memory, you should lock the 
handle to the 'SICN' once the resource is loaded. Notice that the P1otSICN procedure 
dereferences the ' SICN' handle, adds an offset, and copies the resulting value. If the ' SICN' 
list moves in memory at this time, the bitmap's baseAddr is useless. 
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To play it safe, P lot SICN saves a copy of the master pointer flags associated with the relocatable 
block, locks the block with a call to HLock, and restores the flags after calling _CopyBits. 
You should never examine, set, or clear these flags directly; you should always use the routines 
which are provided by the Memory Manager and Resource Manager. Note that it is not necessary 
to check the value of the flag after getting it. 


Pascal 


PROCEDURE PlotSICN(theRect: Rect; theSICN: SICNHand; theIndex : INTEGER); 
VAR 


state : SignedByte; { we want a chance to restore original state } 
srcBits : BitMap; ( built up around 'SICN' data so we can CopyBits ) 
BEGIN 
( check the index for a valid value ) 
IF (GetHandleSize(Handle(theSICN)) DIV sizeof(SICN)) » theIndex THEN 
BEGIN 
( store the resource's current locked/unlocked condition ) 
state :- HGetState(Handle(theSICN)); 
( lock the resource so it won't move during the CopyBits call ) 
HLock (Handle (theSICN)); 
( set up the small icon's bitmap ) 
(SPUSH) 
(SR-) ( turn off range checking ) 
srcBits.baseAddr :- Ptr(G8theSICN^^[theIndex]); 
(SPOP) 
srcBits.rowBytes :- 2; 
SetRect(srcBits.bounds, 0, 0, 16, 16); 
( draw the small icon in the current grafport ) 
CopyBits(srcBits,thePort*.portBits, srcBits.bounds, theRect, srcCopy, NIL); 
{ restore the resource's locked/unlocked condition ) 
HSet State (Handle(theSICN), state); 
END; 
END; 
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C 


void PlotSICN(Rect *theRect, SICNHand theSICN, long theIndex) ( 
auto char state; /* saves original flags of ‘SICN' handle */ 
auto BitMap SrcBits; /* built up around 'SICN' data so we can CopyBits */ 


/* check the index for a valid value */ 
if ((GetHandleSize(Handle(theSICN)) / sizeof(SICN)) » theIndex) { 


/* store the resource's current locked/unlocked condition */ 
state = HGet State ( (Handle) theSICcn) ; 


/* lock the resource so it won't move during the CopyBits call */ 
HLock ( (Handle) theSICNn) ;: 


/* set up the small icon's bitmap */ 
SrcBits.baseAddr = (Ptr) (*theSICN) [theIndex]; 
SrcBits.rowBytes = 2; 

SetRect(&srcBits.bounds, 0, 0, 16, 16); 


/* draw the small icon in the current grafport */ 
CopyBits (&srcBits, & (*qd.thePort) .portBits, &srcBits.bounds, theRect, srcCopy, nil); 


/* restore the resource's locked/unlocked condition */ 
HSetState ( (Handle) theSICN, state); 


That Was Easy 


Now that you've seen it done, it looks pretty easy. With minor modifications, some of the 
techniques in this Note could also be used to plot a bitmap of any dimension. 


Further Reference: 


Inside Macintosh, Volume I, QuickDraw 


Inside Macintosh, Volume I, Toolbox Utilities 

Inside Macintosh, Volume IV, The Memory Manager 

Technical Note #41, Drawing Into an Off-Screen BitMap 
: Technical Note #55, Drawing Icons 
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#253: 'SICN' Tired of Large Icons in Menus? 


Revised by: Dennis Hescox October 1989 
Written by: Dennis Hescox August 1989 


This Technical Note describes a new facility of the Menu Manager which allows you to add 
reduced icons and small icons to your menus. 
Changes since August 1989: Corrected references to SetItemCmd from Set ItmCmd. 





Since the release of MultiFinder, you may have noticed the appearance of small icons ('SICN')in 
the menus of some System Software. At that time, the Menu Manager was modified to allow the 
capability of showing both ' SICN' resources and ' ICON" resources reduced to ' SICN' size. 


How to Add Less 
To add one of the smaller icons to a menu item with Rez or ResEdit, do the following: 
Reduced Icon 


* Place a value of $1D into the cmdChr field of the menuItem. 
e Place the resource ID number of the ' ICON' to use, minus 256, into the 
itemIcon field of the menuItem. 


Small Icon 


Place a value of $1E into the cmdChr field of the menuItem. 
* Place the resource ID number of the ' SICN' to use, minus 256, into the 
itemIcon field of the menuItem. 


In the ResEdit ' MENU’ template, the cmdChr field is called "Key equiv" and the itemIcon field 
is called "Icons." 


For setting or changing the menu from within your program, use the following: 


SetItemCmd (theMenu, item, $1D) ( mark menu item as having a reduced icon ) 
SetItemIcon (theMenu, item, icon) 


Set ItemCmd (theMenu, item, $1E) { mark menu item as having a SICN } 
SetItemIcon (theMenu, item, icon) 
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Note that the resource ID that you indicate to the Menu Manager is 256 less than the icon's real 
resource ID. This means that you can only use icons starting with resource ID of 257 (remember 
that a zero indicates no icon). Figure 1 illustrates a menu with ' SICN' resources in the first three 


es anormal 'ICON' in the fourth item, and a reduced version of the normal ' ICON' inthe 
th item. 





Dj Remember 
@ Screen 






Figure 1-Menu Containing a 'SICN', an 'ICON', and a Reduced 'ICON' 


You Win Some; You Lose Some 


Note that this new facility does not come for free. A menu item that contains a 'SICN' ora 
reduced icon cannot also have a command key equivalent. Because the addition of a smaller icon 
must be somehow recorded into the existing menu record, the cmdChr field of your menu item 


that used to contain the command key equivalent is now used to indicate both the command key to 
use or the use of a smaller icon. 


Further Reference: 


* Inside Macintosh, Volume I, The Menu Manager 
* Inside Macintosh Volume V, The Menu Manager 
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#254: Macintosh Portable PDS Development 
Written by: Dennis Hescox October 1989 





The Technical Note describes the unique aspects of the Macintosh Portable Processor Direct Slot 
(PDS), including the severe limitations in its use. 





The internal operating environment of the Macintosh Portable is unique within the Macintosh 

family due to the additional design goals that are not normally applied to other Macintoshes. In 

particular, two of these goals which limit the use of the PDS are that the unit shall have a long 

(eight hour) battery operation life and that the unit shall meet all FCC regulations, including the 

Pa operate on commercial aircraft (provided that the FCC doesn't bar all portables in the near 
ture). 


I've Got a Bad Feeling About This 


Because of these design goals and the subsequent limitations on the use of the PDS, you must 
severely limit your card design for the Macintosh Portable. 


The first and foremost limitation is that the PDS has no power budget for your card. Seeing 
that there are +12v and +5v connections on the PDS connector, we all realize that you could draw 
some power directly from the Macintosh Portable. Please don't do it. Instead, you should add 
your own power supply (i.e., battery) to your board, thus controlling your own destiny (or at least 
the destiny of your PDS board) and ensuring that the Macintosh Portable has the longest battery life 
of any portable on the market. You are the best judge as to whether or not your board needs to run 
continuously when the Macintosh Portable is in sleep mode, therefore requiring a long current life. 
You might find that the functionality of your board is only optimal when the Macintosh Portable is 
in full-operating mode (or powered by an external source), and in this case, you could conserve its 
current demands. 


For those of you who are convinced that your product is so important that your users will overlook 
a 50% reduction in their system operating time, Table 1 shows a worst-case power budget that 
could apply. 


Power Supply Operating state Sleep State 
+5 V, always on 50 mA maximum 1 mA maximum 


+5 V, switched. 0 mA maximum 
+12 V 25 mA maximum 0 mA maximum 


TT MM 


* The 50 mA maximum applies to the loads of the 
switched and unswitched +5 V supplies. 


Table 1-Worst-Case Power Budget 
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The second limitation is that to meet FCC limits on radio frequency emissions, no connector or 
cable attached to an expansion card can penetrate the case of the Macintosh Portable. 


So Why Have a PDS Connector at All? 


The decision to include the PDS connector is a recognition that we can't know it all. Although it 
may seem that next to no power availability and absolutely no custom cables to the outside world 
would block all possible products, providing the expansion connector allows for that spark of 
genius for which developers are known and the unanticipated product which usually results. So, if 
after all these dire wamings you still want to proceed, following are the available details (at least 
until Designing Cards and Drivers for the Macintosh can be updated). 


Hang On 
The PDS in the Macintosh Portable provides the microprocessor address, control, data, clock 


power, and Macintosh Portable-specific lines for your expansion card's use. Table 2 lists these 
signals, while Table 3 lists their descriptions. 





Pin Number Row A Row B Row C 
1 GND GND GND 
2 45V 45V T5V 
3 +5V +5V +5V 
4 +5V +5V +5V 
5 /DELAY.CS /SYS.PWR /NPA 
6 /BR /BGACK 
7 /BG /DTACK R/W 
8 /LDS /LDS /AS 
9 GND +5/OV Al 
10 A2 A3 A4 
11 AS A6 A7 
12 A8 A9 A10 
13 All A12 A13 
]4 A14 A15 A16 
15 A17 A18 SLOT.A19 
16 ACCO ACCI nc ` 
17 nc SLOT.CSO SLOT.CSI1 
18 /SLOT.UW SLOT.OE /SLOT.LW 
19 SLOT.A20 +12V DO 
20 D1 D2 D3 
21 D4 DS D6 
22 D7 D8 D9 
23 D10 D11 D12 
24 D13 D14 D15 
25 +5/3.7V +5V GND 
26 Al9 A20 A21 
27 A22 A23 E 
28 FCO FC1 FC2 
29 /IPLO /IPL1 /IPL2 
30 /BERR /EXT.DTACK 
/SYS.RST 
31 GND 16M GND 
32 GND GND GND 





Table 2~Macintosh Portable 68000 Direct Slot Expansion Connector Pinouts 
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Mnemonic Description 


nc No connection 


GND Logic ground 

DO-D15 Unbuffered data bus, bits 0 through 15 

A1-A23 Unbuffered address bus, bits 1 through 23 

16M 16 MHz clock 

/EXT.DTACK External data transfer acknowledge. This signal is an 
input to the processor logic glue that allows for external 
generation of the /DTACK signal. 

E E (enable) clock 

/BERR Bus error signal generated whenever /AS remains low 
for more than about 250 ms 

/ZIPLO-/IPL2 Input priority level lines 0 through 2. 

/RESET Initiates a system reset 

/HALT Indicates that the processor should suspend bus 


activity. /HALT and /RESET are tied together but can 
be internally disconnected for independent action 


/AS Address strobe 

/UDS Upper data strobe 

/LDS Lower data strobe 

R/W Defines bus transfer as read or write signal 
/DTACK Data transfer acknowledge 

/BG Bus grant 

/BGACK Bus grant acknowledge 

/BR Bus request 

NMA Valid memory access 

[NPA Valid peripheral address 
FCO-FC2 Function code lines 0 through 2 
/SLOT.CSO-1 Reserved 

SLOT.OE Reserved 

/SLOT.INS Reserved 

SLOT.A19-20 Reserved 

/SLOT.UW Reserved 

/SLOT.LW Reserved 


EE EE EE OO 


Table 3-Functional Description of the Macintosh Portable PDS Signals 


The signals listed in Tables 2 and 3 are presented to your PDS card through a Euro-DIN 96-pin 
socket connector on the main logic board. If components are to be mounted on the top side of the 
card, the plug connector should have compliant pins (i.e., force fit insertion) rather than 
solder-type pins for connection to the expansion card. 
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Currently, you can order these Euro-DIN 96-pin connectors (which meet Apple specifications) 
from: AMP Incorporated, Harrisburg, PA 17105. 


Disclaimer: This listing for AMP Incorporated neither implies nor constitutes an 
endorsement by Apple Computer, Inc. If your company supplies these 


connectors and you would like to be listed, contact us at the address in 
Technical Note #0. 









508 , 
am | WE T 
| 2.54 (.100) 52 1150 (.100) 
mum. 


(204) (452) 


E mr 
p 
(.114) 
Three-row pin connector Dirnensions are 
96 contact positions in millimeters 
2.54 mm (.100) spacing pins with inches in 
Gold plated, 20 microinches, over nickel plate parentheses. 


Figure 1—96-Pin Plug Connector 


Due to the limited space within the Macintosh Portable's case, your card is limited to the size 


indicated in Figure 2. We highly recommend the use of CMOS circuits to reduce the total power 
necessary for your card's operation. 
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Dimensions are in Millimeters. 





Figure 2-PDS Expansion Card Dimensions 


Further Reference: 


* Designing Cards and Drivers for the Macintosh 
* Guide to the Macintosh Family Hardware 
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#255: Macintosh Portable ROM Expansion 
Written by: Dennis Hescox October 1989 


This Technical Note explains the practice of and theory behind compatible use of the expansion 
ROM in the Macintosh Portable. 





Due to the unique nature of the Macintosh Portable, developers now have the ability to add ROM to 
the Macintosh. To provide for compatible shared use of this ROM space with Apple and other 
developers, this Note describes the feature and suggests methods of shared implementation. 


Address Space 


The Macintosh Portable contains 256K of processor ROM, which is fundamentally the same as the 
ROM in the Macintosh SE. This ROM is located at the low end of a 1 MB ROM space. With an 
expansion card, one can either completely replace the 1 MB ROM or simply add an additional 4 
MB of ROM. The original 1 MB of address space is reserved for use by Apple, but the 
additional 4 MB address space is available for third-party developers. 


Apple reserved ROM space is located from $90 0000 through $9F FFFF. You can replace this 
ROM space with an expansion board, thus overriding these ROMs; however, if you override these 
ROMs your machine will no longer work with most applications. This ability to override the 
original ROMs is intended for Apple in the event that a ROM upgrade is ever necessary for the 
Macintosh Portable. Developers should use the 4 MB ROM address space from $A0 0000 through 
$DF FFFF, which is illustrated in Figure 1, for expansion. 


Since Apple could provide a ROM upgrade (on a ROM expansion board), we recommend that 
developers use a standard 32-pin DIP socketed ROM part for any expansion board. Following this 
recommendation ensures that the user will never have to choose between an Apple ROM upgrade 
and a third-party expansion board, since Apple could provide sockets for third-party ROMs if we 
were to produce such an upgrade. 
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Reserved Hardware 


Expansion 


RAM/ROM Overlay 





Figure 1-Macintosh Portable Memory Map 


Expansion ROM Board 


If Apple were to produce an expansion ROM board for an upgrade, it would have the following 
characteristics. Side one would contain four 32-pin ROM sockets compatible with 128K x 8 bit or 
512K x 8 bit ROMs, a dip switch for choosing between 128K or 512K socket address sizes, and 
appropriate decoupling capacitors. Side two would contain Apple's expansion ROMs and any 
additional circuitry. This design implies that developers would be able to use at most either 512K 
or 2 MB of the total 4 MB expansion space. 


When designing your own expansion board, remember that it must contain circuitry for decoding, 
controlling, and buffering, and it should use CMOS, since the Macintosh Portable restricts ROM 
expansion boards to a maximum of 25ma. The number of wait states inserted depends upon the 
DTACK generated by your board, which connects to the Macintosh Portable through a single 
50-pin connector (slot). The machine provides all of the appropriate signals (address bus, data 
bus, and control) to the expansion slot, where they are decoded into chip selects and routed to 
address and data buffers. These signal names and descriptions are illustrated in Figure 2 and 
described in Table 1. It is also important to buffer the address and data buffers to reduce capacitive 
loading. 
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Figure 2-Internal ROM Expansion Connector Signals 


Pin Number Signal Name Signal Description 

1 +5V Voc 

2-24 A1-23 Unbuffered 6#HCOOO address 
signals A1-23 

25-26 GND Logic Ground 

27 /DTACK /DTACK input to 68HCO000 

28 /AS 68HCO00 address strobe signal 

29 /ROM CS Permanent ROM chip select 
signal. Selects in range $90 0000 
through $9F FFFF. 

30 16 Mhz clock 16 Mhz system clock. 

31 /EXT DTACK External /(DTACK 
signal that disables main system 
/DTACK 

32 /DELAY CS This signal is generated 
by the addressing PAL and is used to 
put the ROM board into the idle mode 
by inserting multiple wait states. 

33-48 D0-15 68HC000 unbuffered data 
signals DO-15 

49-50 +5V Væ 





Table 1-Internal ROM Expansion Connector Signal Descriptions 
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7.62 [.300] rear cover. Both Sides. 5.37 (211 
2.34 (.092) j dnx 


-27.28 [-1.074] 0 68.18 [2.684] 
Dimensions are in Millimeters [Inches] 


Figure 3-Internal ROM Expansion Board Guidelines 


Software Standards 


For the purposes of expansion ROM, Apple has introduced Electronic Disks (EDisks), which 
appear to the user as very fast, silent disk drives. The EDisk driver supports EDisks, which use 
RAM or ROM as their storage media. 


ROM EDisks, which can be produced by third parties, are connected to the system using the 
internal ROM expansion slot. The 4 MB address space allocated for this type of expansion 
supports any number of ROM EDisks, as long as they start on a 64K boundary (their size may 
exceed 64K). ROM EDisks behave like RAM EDisks, except that they are read-only and cannot be 


resized. 
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The EDisk Driver 


The EDisk driver provides a system interface to EDisks similar to that provided by the Sony and 
SCSI disk drivers. It supports 512 byte block I/O operations and does not support file system 
tags. The EDisk driver isa ROM 'DRVR' resource with an ID of 48, RefNum of -49, and driver 
name of “.EDisk”. Since it is a disk driver, it also creates a Drive Queue Element for each EDisk. 
Information on how these driver calls apply to the Sony driver appear in the Disk Driver chapters 
of Inside Macintosh, Volumes II, IV, & V. 


EDisk Implementation Details 


The remainder of this section describes some of the implementation details, data formats, and 
dE used by the EDisk driver that may be useful for developers who want to produce ROM 
EDisks. 


Data Checksumming 


To provide better data integrity, the EDisk driver supports checksumming of each data block, 

Which is computed when a write is performed to a block and checked on every read operation. It 

computes a 32-bit checksum for each 512-byte block. This calculation is performed by adding 

each longword in the block to a running longword checksum, which is initially zero, and is rotated 

a oe bit before each longword is added. The following assembly code demonstrates this 
gonthm: 


Lea TheBlock, a0 AO is pointer to the block to checksum 

Moveq. L #0,D0 ; DO is the checksum, initially zero 

Moveq.L #(512/4)-1,D1 ; loop counter for 1 block (4 bytes per iteration) 
@Loop Rol.L #1,DO ; rotate the checksum 

Add, L (AO) *,DO ; add the data to the running checksum 

Dbra D1, @Loop ; loop through each longword in the block 


Internal ROM EDisk Details 


When the EDisk driver is opened, it searches the address range from the base of the system ROM 
to $00E0 0000 for internal ROM EDisks. An internal ROM EDisk must begin with an EDisk 
header block, which must start on a 64K boundary (but may be any size). If a valid header block 
is found, it is compared to all other known headers, and if it is identical to another, it is ignored to 
eliminate duplicates caused by address wrapping. If the header block is unique, the EDisk driver 
supports it and creates a drive queue entry for it. The driver can support any number of internal 
ROM EDisks, and it is limited only by the address space allocated for ROM. 


EDisk Header Format 


There is a 512-byte header block associated with ROM EDisks. This header describes the layout of 
the EDisk and uniquely identifies it. The general format of the header block is described below. 
The EDisk header marks the beginning of an EDisk, and it should occur at the beginning of the 
ROM space that is used for EDisk storage (i.e., starting at the first byte of a 64K ROM block). 


EDiskHeader Record 0, increment ; layout of the EDisk signature block 
HdrScratch DS.B 128 ; Scratch space for r/w testing and vendor info 
HdrBlockSize DS.W 1 ?; size of header block (512 bytes for version 1) 
HdrVersion DS.W 1 ; header version number (this is version 1) 
HdrSignature DS.B 12 ; 45 44 69 73 6B 20 47 61 72 79 20 44 
HdrDeviceSize DS.L 1 i size of device, in bytes 

HdrFormatTime DS.L 1 ; time when last formatted (pseudo unique ID) 
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HdrFormatTicks DS.L 
HdrCheckSumOff DS.L 
HdrDataStartOff DS.L 
HdrDataEndOff DS.L 
HdrMediaIconOff DS.L 
HdrDriveIconOff DS.L 
HdrWhereStroff DS.L 
HdrDriveInfo DS.L 
DS.B 
EDiskHeaderSize EQU 
ENDR 
HdrScratch 
HdrBlockSize 
HdrVersion 
HdrSignature 
HdrDeviceSize 
HdrFormatTime 
HdrFormatTicks 
HdrCheckSumof f 
HdrDataStartOff 
HdrDataEndOff 


; ticks when last formatted (pseudo unique ID) 
; offset to the Checksum table, if present 
; Offset to the first byte of data storage 
7 Offset to the last byte-«l of data storage 
; Offset to the media Icon and Mask, if present 
offset to the drive Icon and Mask, if present 
offset to the Get Info Where: string, if present 
; longword for Return Drive Info call, if present 
12-* ; rest of block is reserved 
; size of EDisk header block 


se me 


* (H2 HP D pb RF HE H 


is a 128-byte field that is used for read and write testing on RAM 
EDisks to determine if the memory is ROM or RAM. On ROM 
EDisks, it should be filled in by the vendor with a unique string to 
identify this version of the ROM EDisk (e.g., "Copyright 1989, 
Apple Computer, Inc. System Tools 6.0.4 9/5/89”). 


is a 2-byte field that indicates the size of the EDisk header block. The 
size is currently 512 bytes. 


is a 2-byte field that indicates the version of the EDisk header block. 
The version number is currently $0001. 


is a 12-byte field that identifies a valid EDisk header block. The 
signature must be setto 45 44 69 73 6B 20 47 61 72 79 
20 44 in hexadecimal. 


is a 4-byte field that indicates the size of the device in bytes, which 
may be greater than the actual usable storage space. One might also 
think of the device size as the offset (from the beginning of the header 
block) of the last byte of the storage device. 


is a 4-byte field that indicates the time of day when the EDisk was last 
formatted. The EDisk driver updates this for RAM EDisks when the 
format control call is made. This information may be useful for 
uniquely identifying a RAM EDisk. 


is a 4-byte field that indicates the value of the system global Ticks 
when the EDisk was last formatted, which should be a unique 
number. The EDisk driver updates this for RAM EDisks when the 
format control call is made. This information may be useful for 
uniquely identifying a RAM EDisk. 


is a 4-byte field that is the offset (from the beginning of the header 
block) of the checksum table, or zero if checksumming should not be 
performed on this EDisk. 


is a 4-byte field that is the offset (from the beginning of the header 
block) of the first block of EDisk data. 


is a 4-byte field that is the offset (from the beginning of the header 
block) of the byte after the end of the last block of EDisk data. 
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HdrMediaIconOff is a 4-byte field that is the offset (from the beginning of the header 
block) of the 128-byte icon and 128-byte icon mask, which represents 
the disk media. An offset of zero indicates that the EDisk driver 
should use the default media icon for this EDisk. 


HdrDriveIconOff is a 4-byte field that is the offset (from the beginning of the header 
block) of the 128-byte icon and 128-byte icon mask, which Tepresents 
the disk drive physical location. An offset of zero indicates that the 
EDisk driver should use the default drive icon for this EDisk. 


HdrWhereStrOff is a 4-byte field that is the offset (from the beginning of the header 
block) of the Pascal string that describes the disk location for the 
Finder Get Info command. An offset of zero indicates that the EDisk 
driver should use the default string for this EDisk. 


HdrDriveInfo is a 4-byte field that should be returned by the drive information 
control call. A value of zero indicates that the EDisk driver should use 
the default drive info for this EDisk. 


You should not override the default media or drive icons without first giving serious consideration 
as to how a different icon will affect the user interface. What often appears to be a clever idea for a 
cute icon usually turns out to be a source of frustration for the user when deciding what the item is 
and where it is physically located. 


Some Final Thoughts 
Do Not Use More Space Than You Need 


As wonderful and indispensable as your ROM product may be, users may wish to also use ROMs 
from another developer. Although ROM address space is quite large (in today's terms), board 
space and number of ROM chip sockets is limited. If you use only the space you really need and 
leave room (address space and empty chip sockets) in your ROM product to add other ROMs, 
users will never have to make a choice between your product and another, unanticipated stroke of 
genius. 


Keep It Relocatable 


Just because your code is in ROM does not mean that it will always reside at a specific address. 
When moving your ROM to another board (an Apple upgrade or another third-party board), users 
should neither have to worry about address range conflicts nor socket location. In addition, Apple 
may implement ROM expansion in a future product with expanded or different address space; 
keeping your ROM code relocatable could mean the difference between additional sales or 


Incompatibility and upgrades. 


Further Reference: 


* Inside Macintosh, Volume II, IV, & V, The Disk Driver 
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#256: Globals in Stand-Alone Code? 


Written by: Keith Rollin & Keithen Hayenga October 1989 
Special Guest appearance by Clarus the dogcow 





This Technical Note, with the help of a special guest appearance, discusses the possibilities of 
using global variables in stand-alone code, a task previously thought impossible. 





Dear Clarus, 


I was attending a social gathering of PC and UNIX programmers the other day, when some of my 
friends starting discussing modular code segments. We were speaking of tossing off routines in 
Pascal or C, linking, saving them off to disk, and then hammering out a shell application that 
would load and execute them at run-time. Generally, a good time was had by all. The hostess was 
particularly dazzling in her “Rude Dog" t-shirt. 


However, recently something happened that changed my world. I was offered the chance to 
program a Macintosh. I couldn’t believe it when I heard it, and, of course, I jumped at the chance. 
I've been programming for many years, but have never used my abilities to their fullest potential. 
Now I could realize all of that, and more. 


So I loaded up on everything I needed: Macintosh Ici, tons of RAM, all five volumes of Inside 
Macintosh, every single Technical Note, and the paragon of development systems, MPW. In short 
time I had my shell done, and I then set into programming the stand-alone modules that would be 
loaded and executed at run-time. Very quickly, I ran into a problem. 


Clarus, would you believe that MPW doesn’t allow global variables in stand-alone code? When I 
try using them, the MPW linker gives me some sort of bogus message like, “Data Initialization 
code is not being called. (Error 57).” I mean, other development systems manage it. Isn’t the 
Macintosh supposed to be a totally flexible environment to program in? 


What do Ido? All of my PC friends are laughing at me. 
-PC Weenie who's seen the Light of the Macintosh 


Dear PC, 


The problem with accessing global variables from stand-alone code resources is a very ancient and 
time-honored one. It all hinges on the availability of the A5 register. This register is used to access 
a 64K area of memory that contains an application’s jump table, global variables, and 32 rather 
mysterious bytes called the application’s parameters. Because you are sharing the same heap as an 
application when your stand-alone code resource is executed, the application is busy using A5 and 
won't share it with you. 
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That's the conflict. So what's the solution? Reflection upon your youthful days should provide 
you with an answer. As with any bully who won't share his toys with you, you'll have to go and 
take them away by force (an act that Clarus fully endorses). You need to write four routines: 
MakeA5World, SetA5World, RestoreA5World,andDisposeA5World. By calling these 
routines at the right time, you can manage your own A5 world, separate from the host 
application's. 


There are basically two types of stand-alone code that need globals: the kind that just needs some 
because the programmer is too lazy to pass local variables as parameters to subroutines and the 
kind that would like some sort of persistence in its data (i.e., the data hangs around in memory 
across calls to the stand-alone code). 


The first kind is easy. When the module is executed, it creates an AS world, does its thing, and 
then tears down the A5 world, making sure to restore the host application's world. Such a routine 
would look something like the following: 


TYPE 
A5RefType - Handle; 


VAR 
global: integer; 


PROCEDURE Main; 


VAR 
ASRef: ASRefType; 
oldA5: Ptr; 


BEGIN 
MakeASWorld{A5Ref); 
oldA5 :- SetA5World(A5Ref); 


DoSomeStuff; 


RestoreA5World(oldA5, ASRef); 
DisposeA5World(ASRef) 
END; 


The second kind is a little trickier and requires the cooperation of the host application. In this case, 
what we need is the ability to pass back a reference to our global variable section so we can easily 
restore it the next time we are invoked. In addition, we need some sort of indication of whether or 
not this is the first or last time we are being called. This kind of routine could look like the 


following: 
PROCEDURE Main (code: integer; VAR A5Ref: ASRefType); 


VAR 
oldA5: Ptr; 


BEGIN 
IF code = kFirstTime THEN 
MakeA5World(A5Ref); 
oldA5 := SetA5World(A5Ref); 


DoSomeStuff; 


RestoreA5World(oldA5, ASRef); 
IF code = kLastTime THEN 
DísposeA5World (ASRef) 
END; 


eS 
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(Clarus’ PUG-faced neighbor would like to point out that you could also just check to see if the 
ASRef being passed to you is NIL or not to determine if you need to create an A5 world.) 


PI bet you're asking yourself right now, "OK, but what are these magic routines: 
MakeASWorld, SetA5World, RestoreA5World, and DisposeA5World?" Well, Clarus 
is glad you asked. These routines are very simple and are basically glue to the same routines that 
initialize the run-time environment for your application: 


PROCEDURE MakeASWorld (VAR ASRef: ASRefType); 


BEGIN 
ASRef := NewHandle (A5Size); 
HLock (A5Ref) ; 
A5Init(Ptr(ORD4(ASRef^) + ASSize - 32)); 
HUnlock (A5Ref) ; 
END; 


FUNCTION SetASWorld(ASRef: ASRefType): Longint; 


BEGIN 

HLock (A5Ref) ; 

SetA5World :- SetA5(Longint(ASRef^) + ASSize - 32); 
END; 


PROCEDURE RestoreAS5World(oldA5: Longint; ASRef: ASRefType); 


BEGIN 
IF Boolean(SetA5(oldA5)) THEN; 
HUnlock (ASRef) ; 

END; 


PROCEDURE DisposeA5World(ASRef: ASRefType) ; 


BEGIN 
DisposHandle (ASRef); 
END; 


Like I said, very simple. Even Clarus’ evil twin brother, Oscar, could write them. They are really 
only interfaces to the run-time procedures A5Size and ASInit. The interface to these routines is 
as follows: 


FUNCTION A5Size: Longint; 
C; EXTERNAL; 


PROCEDURE A5Init(myA5: Ptr); 
C; EXTERNAL; 


Ah, Clarus sees understanding in your eyes. “So these are the magic routines," you are thinking. 
“They are the magic incantations that allow me to stop beating my head up against Inside Macintosh 
and let me get on with my work. Why didn't Apple ever tell me about these before?" To tell the 
truth, Clarus isn't too sure. 


A5Size finds out how much memory we need for our A5 world. This memory consists of two 
parts: memory for our globals, and memory for our application parameters. A5Init takes a 
pointer to our A5 globals and initializes them to their appropriate values. How these work takes a 
little explaining. 


When MPW's linker links your program together, it has to somehow describe what your globals 
area should look like. At the very least, it needs to keep track of how large your globals section 


See 
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should be. At the very not-least, it needs to specify what values to put into your globals area. 
Normally, this means setting everything to zero, but some crufty languages like C allow one to 
specify preinitialized globals. 


The linker creates a packed data block that describes all of this and sticks it into a segment called 
$A5Init. Also included in this segment are the routines called by the MPW run-time initialization 
package to act upon this data. A5Size and ASInit are two such routines. A5Size looks at the 
field that holds the unpacked size of the data and returns it to the caller. A5In it is the beast 
responsible for unpacking the data into your globals section. 


Clarus would like to remind the gentle reader that in the Macintosh application environment, A5 
points to the top of the globals section. This should explain the math that MakeA5World is 
performing. It gets a pointer to the start (i.e., bottom) of our globals area, adds the value returned 
by A5Size, and subtracts 32 to compensate for the fact that A5Size includes room for the 
application parameters. This action leaves us with a pointer to the memory location that divides the 
global variables and application parameters (if your photographic memory is out of film, just look 
at the picture on page II-19 of Inside Macintosh). 


The propeller-heads over in the HyperCard group would like Clarus to remind you of something 
else: if you are planning on making any callbacks to the host application (as HyperCard and Apple 
File Exchange allow you to do), you have to temporarily restore that host's A5. Otherwise, as said 
propeller-heads put it, "you will be singing la bomba" when the host finds a different set of 
variables hanging off of A5. Making sure that you call Set A5 before and after your callbacks 
cures i pem A sample 'XCMD ' resource at the end of this Technical Note demonstrates 
how to do this. 


One last thing. The Greeks believed that there was something controlling the universe called “The 
Natural Order of Things." This philosophy stated that objects sought out their natural position in 
the world. This explains why water rains from the sky (to get back into the oceans) and why rocks 
fall when you drop them (to get back to the ground). This philosophy also explains why the new 
AS handling routines (A5Init, A5Size, and some others that they rely upon) normally go into a 
' CODE' segment called $ASTnit; it's because that's where they naturally want to go. However, 
we don't want them there; we want them included in the same segment as our stand-alone code. 


Fortunately, much in the same way you can pick up a rock and move it somewhere else (preferably 
to your neighbor's yard), you can move these routines into your code segment. This is done by 
using the -sg option of the MPW linker. For instance, in the following example, Clarus simply 
moofed! the statement -sg Sorter, and everything was stuffed into the code resource named 
Sorter. 


Clarus hopes this helps. 


A Note From the Management 


The management of this publication would like to thank Clarus for providing the preceding 
information. However, we felt it prudent to include the additional caveat, to wit, that the problems 
associated with multisegmented code are not directly addressed with these techniques. The 
routines for dealing with loading additional segments, ensuring that the resource map chain's 
integrity is maintained, and allocating space for a jump table have not, at this time, been 
formulated. We, the management, hope to coerce Clarus into a caffeine-induced haze sufficient 
enough to cover this topic in the future. 
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Full Source Sample 


Following is the source code to a HyperCard ' XCMD' that uses globals. This ' XCMD' accepts a 
list of numbers, one at a time, then sorts them and passes them back to HyperCard. It can receive 
any of four commands: kFirstTime, kAddEnt ry, kSortEntries, and kLastTime. 
kFirstTime tells the ' XCMD' to create an A5 world and initialize it. kAddEnt ry includes a 
number to be added to a global and persistent list of numbers to be sorted. kSortEnt ry instructs 
the ' XCMD' to sort the list of numbers and pass them back to HyperCard. Finally, kLast Time 
is passed to the ' XCMD' to tell it to shut down and dispose of any working memory it allocated. 
Throughout all of this, calls are made back to HyperCard, showing how to temporarily swap 
HyperCard's A5 back in during the callback. 


HyperCard Script 


on mouseUp 


global A5 
Sorter 1, "A5" -- Initialize that puppy 
if the result is empty then 
Sorter 3, A5, 2 -- Add some numbers to the list 


Sorter 3, A5, 6 
Sorter 3, A5, 9 
Sorter 3, AS, 12 
Sorter 3, AS, 7 


Sorter 4, A5 -- sort them and print them 
Sorter 2, A5 -- Dispose of our data 

else 
put the result 

end if 


end mouseUp 


Make File (Sorter.make) 


OBJECTS = Sorter.p.o 


Sorter ff Sorter.make (OBJECTS) 
Link -w -t XCMD -c kaar -rt XCMD=9999 ð 

-m ENTRYPOINT -sg Sorter d 
{OBJECTS} ð 
"ILibraries)HyperXLib.o" ð 
"[Libraries)Interface.o" ð 
"(Libraries)Runtime.o" ð 
"(PLibraries)PasLib.o" 2 
-o Sorter 

Sorter.p.o f Sorter.make Sorter.p 

Pascal Sorter.p 


EE EE 
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Pascal File (Sorter.p) 


$2«*) ( This allows the Linker to find "ENTRYPOINT" without our 
having to put it in the INTERFACE section } 


UNIT Fred; 
INTERFACE 


USES Types, Memory, OSUtils, HyperXCmd; 


IMPLEMENTATION 
TYPE 
A5RefType - Handle; 
LongArray = ARRAY (0..0) OF Longint; ( These define our list of entries } 


LongPointer = “LongArray; 
LongHandle = “LongPointer; 


CONST 
kFirstTime = 1; 
kLastTime = 2; 
kAddEntry = 3; 
kSortEntries = 4; 


being called for the first time. Initialize. } 
being called for the last time. Clean up. } 

being called to add an entry to our list to sort. } 
being called to sort and display our list. } 


it 


kCommandIndex = 1; { Parameter 1 holds our command number. } 

kA5RefIndex = 2; ( Parameter 2 holds our A5 world reference, ) 

kEntryIndex = 3; ( Parameter 3 holds a number to add to our list. ) 
VAR 

gHostA5: Longint; ( The saved value of our host's (HyperCard's) AS. ) 

gNumOfEntries: Longint; ( The number of entries in our list. ) 

gEntries: LongHandle; ( Our list of entries. Gets expanded as needed. ) 


( The following 2 functions are the ones that set up and maintain our AS world. You must 
Link with RunTime.o or CRunTime.o to call them. ) 


PROCEDURE ASInit (myAS: Ptr); 
C; EXTERNAL; 


FUNCTION ASSize: Longint; 
C; EXTERNAL; 


( Forward reference to the main procedure. This is so we can jump to it from ENTRYPOINT, 
which represents the beginning of the XCMD, and is what HyperCard calls when it 


calls us, } 


PROCEDURE Sorter(paramPtr: XCmdPtr); 
FORWARD; 


PROCEDURE ENTRYPOINT (paramPtr: XCmdPtr); 
BEGIN 
Sorter (paramPtr) ; 
END; 


{ The next 4 routines are our glue to the A5 maintenance routines, 


MakeA5World calls A5Size to get the amount of memory required for our A5 world. It 
then calls NewHandle to allocate that memory, and A5Init to initialize it. 


TT OO eee 


#256: Globals in Stand-Alone Code? 6 of 10 


SetA5World takes care of swapping in our A5 world. It locks down the handle that 
holds our A5 data, sets A5 to point to it, and returns the original A5, 


RestoreA5world reverses the effects of SetA5Worid. It restores AS to the value 
our host application needs, and unlocks our block of global data so as not 
to fragment our host's heap. 


DisposeA5World is called when we are all done. It is in charge of disposing our 
global data. Right now, this is just a call to DisposHandle. 


PROCEDURE MakeA5World(VAR A5Ref: A5RefType); 


BEGIN 
ASRef :- NewHandle(A5Size); 
HLock (A5Ref) ; 
A5Init (Ptr (ORD4 (A5Ref^) * A5Size - 32)); 
HUnlock (ASRef) ; 
END; 


FUNCTION SetA5World(A5Ref; ASRefType): Longint; 


BEGIN 
HLock (A5Ref) ; 
SetA5World := SetAS(Longint(A5Ref^) + ASSize - 32); 


END; 


PROCEDURE RestoreA5World{oldAS: Longint; A5Ref: ASRefType); 


BEGIN 
IF Boolean(SetA5(oldA5)) THEN; 
HUnlock(A5Ref); 

END; 


PROCEDURE DisposeA5World(A5Ref: ASRefType); 


BEGIN 
DisposHandle(A5Ref); 


END; 


( Utility routines for using the HyperCard callbacks. There are some functions 
that we need to perform many times, or would like to encapsulate into little 


routines for clarity: 


ValueOfExpression - given an index from 1 to 16, this evaluates the expression 
of that parameter, This is used to scoop out the value of the command 
selector, our AS pointer, and the value of the number we are to stick 
into our list of numbers to sort, 


LongToZero - Convert a LONGINT into a C (zero delimited) string. Returns a 
handle that contains that string. 


SetGlobalAt - given the index to one of the 16 parameters and a LONGINT, this 
routines sets the global found in that parameter to the LONGINT. 


FUNCTION ValueOfExpression(paramPtr: XCmdPtr; index: integer): Longint; 


VAR 
tempStr: Str255; 
tempHandle: Handle; 


TT U 
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BEGIN 
ZeroToPas(paramPtr, paramPtr^.params[index]^, tempStr); 
tempHandle :- EvalExpr(paramPtr, -empStr); 
ZeroToPas(paramPtr, tempHandle^, tempStr); 

DisposHandle (tempHandle}; 
ValueOfExpression :- StrToLong(paramPtr, tempStr); 

END; 


FUNCTION LongToZero(paramPtr: XCmdPtr; long: Longint): Handle; 


VAR 
tempStr: Str255; 


BEGIN 
LongToStr(paramPtr, long, tempStr); 
LongToZero :- PasToZero(paramPtr, tempStr); 

END; 


PROCEDURE SetGlobalAt (paramPtr: XCmdPtr; index: integer; long: Longint); 


VÀR 
globalName: Str255; 
hLong: Handle; 


BEGIN 
ZeroToPas (paramPtr, paramPtr^,.params[index]^, globalName); 
hLong :- LongToZero(paramPtr, long): 
SetGlobal(paramPtr, globalName, hLong); 
DisposHandle (hLong); 
END; 


( These 4 routines are called in according to the command passed to the XCMD: 


Initialize - used to initialize our globals area. ASInit will clear everything 
to zero, and set up any pre-initialized variables if we wrote our program 
in C or Assembly, but it can't do everything. For instance, in this XCMD, 
we need to create a handle to hold our list of entries. 

AddAnEntry - Takes the value represented by the 3 parameter passed to us by 
HyperCard and adds it to our list. 

SortEntries - Sorts the entries we have so far. Converts them into a string 
and tells HyperCard to display them in the message box. 

FreeData - We just receive the message saying that we are never going to be 
called again. Therefore, we must get rid of any memory we have allocated 
for our own use. 


PROCEDURE Initialize; 


BEGIN 
gEntries :- LongHandle (NewHandle (0)) ; 


gNumOfEntries := 0; 
END: 


PROCEDURE AddAnEntry(paramPtr: XCmdPtr); 
VAR 
ourA5: Longint; 


tempStr: Str255; 
temp: Longint; 


eee 
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BEGIN 
OurA5 := SetA5(gHostA5); 
temp :- ValueOfExpression(paramPtr, kEntryIndex); 
ourAS :- SetAS(ourA5); 


SetHandleSize(Handle(gEntries), (gNumOfEntries + 1) * 4); 
(SPUSH) {$R-} 
gEntries^^[gNumOfEntries] :- temp; 
(SPOP) 
gNumOfEntries :- gNumOfEntries + 1; 
END; 


PROCEDURE SortEntries(paramPtr: XCmdPtr); 


VAR 
ourAS: Longint; 
i, j: integer; 
fullStr: Str255; 
tempStr: Str255; 
temp: Longint; 


BEGIN 
IF gNumOfEntries » 1 THEN BEGIN 
FOR i := 0 TO gNumOfEntries - 2 DO BEGIN 
FOR j := i + 1 TO gNumOfEntries - 1 DO BEGIN 
IF gEntries^^[(i] > gEntries^^([j] THEN BEGIN 
temp :- gEntries^^[i]; 
gEntries^^[i] := gEntries^^(j); 
gEntries^^[j] :- temp; 
END; 
END; 
END; 
END; 


IF gNumOfEntries > 0 THEN BEGIN 
fullStr :- ''; 
FOR i :- 0 TO gNumOfEntries - 1 DO BEGIN 
{$PUSH} {$R-} 
temp := gEntries^^[i]; 
{$POP} 
ourà5 :- SetA5(gHostA5); 
NumToStr(paramPtr, temp, tempStr); 
ourA5 :- SetA5(ourA5); 
fullStr ss concat(fullStr, ', ', tempStr); 
END; 
delete(fullStr, 1, 2); ( remove the first ", " ) 
ourAS :- SetAS5(gHostA5); 
SendHCMessage (paramPtr, concat('put "', fullStr, '"')); 
OUrAS := SetA5(ourA5); 
END: 
END; 


PROCEDURE FreeData; 


BEGIN 
DisposHandle (Handle (gEntries)); 


END; 


( Main routine. Big Cheese. Head Honcho. The Boss. The Man with all the moves. You 
get the idea. This is the controlling routine. It first checks to see if we have 
the correct number of parameters (sort of). If that's OK, then it either creates 
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a new A5 world and initializes it, or it sets up one that we've previously created. 
It then dispatches to the appropriate routine, depending on what command was passed 
to us. Finally, it restores the host application's AS world, and disposes of ours 
if this is the last time we are being called. } 


PROCEDURE Sorter(paramPtr: XCmdPtr); 


VAR 
command: integer; 
ASRef: ASRefType; 
errStr: Str255; 
A5Name: Str255; 


BEGIN (Main) 


WITH paramPtr^ DO 
IF (paramCount « 2) OR (paramCount » 3) THEN BEGIN 
errStr :- 'Correct usage is: "Sorter «function» «A5» [«entry»]"'; 
paramPtr^,.returnValue := PasToZero(paramPtr, errStr); 
EXIT(Sorter); (leave the XCMD) 
END; 


command ;= ValueOfExpression(paramPtr, kCommandIndex); 


IF command = kFirstTime THEN BEGIN 
MakeASWorld (ASRef); 
SetGlobalAt (paramPtr, kASRefIndex, Longint (ASRef)); 
END 
ELSE BEGIN 
ASRef :- ASRefType (ValueOfExpression(paramPtr, KASRefIndex)); 
END; 


IF (ASRef - NIL) THEN BEGIN 
errStr :- 'Could not get an A5 World!!!'; 
pParamPtr^.returnValue := PasToZero(paramPtr, errStr); 
EXIT(Sorter); (leave the XCMD) 

END; 


gHostA5 := SetASWorld(A5Ref); 

CASE command OF 
kFirstTime: Initialize; 
kAddEntry: AddAnEntry (paramPtr); 
kSortEntries: SortEntries(paramPtr); 
kLastTime: FreeData; 

END; 

RestoreA5World(gHostA5, ASRef); 


IF command = kLastTime THEN 
DisposeA5World(ASRef) 


END; (main) 


THE END. 


Further Reference: 


Inside Macintosh, Volume II, The Memory Manager & The Segment Loader 
Technical Note #110, MPW: Writing Stand-Alone Code 

Technical Note #208, Setting and Restoring A5 

Technical Note #240, Using MPW for Non-Macintosh 68000 Systems 
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#257: Slot Interrupt Prio-Technics 
Written by: Mark Baumwell October 1989 
This Technical Note describes the way interrupt priorities are scheduled, which corrects the 


description of slot interrupt queue priorities in the Device Manager chapter of Inside Macintosh, 
Volume V-426. 





According to Inside Macintosh, Volume V-426, The Device Manager, the SOPrio field of a slot 
interrupt queue element is an unsigned byte that determines the order in which slots are polled and 
interrupt service routines are called. This is incorrect on all Macintosh models prior to the IIci 
that are running a system version earlier than System Software 7.0. 


In reality, slot interrupts of lower priority values have always been called first. However, all new 
Macintosh computers, starting with the Macintosh Ici, as well as all machines running System 
Software 7.0 or later, will have an SIntInstall routine that has been changed to reflect the 
description in Inside Macintosh. 


In addition, the SOPrio field is, and has always been, two bytes long, but the high byte is 
reserved and must be set to zero. 


Apple still reserves priority values 200-255 as documented in Inside Macintosh. 

Note that in any case of slot interrupts with equal priority, the most recently installed interrupt is 
run first, regardless of system version. 

Further Reference: 


* Inside Macintosh, Volume V-426, The Device Manager 
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#258: Our Checksum Bounced 


Written by: Jim Reekes October 1989 


This Technical Note discusses a fix to a SCSI Manager bug which concerns all developers working 
with SCSI and NuBus™ device drivers. 





A Bit of History 


The boot code contained in the ROM has a feature used by the Start Manager to perform a 
checksum on the SCSI driver being loaded. Inside Macintosh, Volume V-573, The SCSI 
Manager, documents this being performed on the Macintosh SE and later models for volumes 
using the new partitioning method. The truth, however, is that that checksum verification was 
med performed due to a bug in the ROM, and because of this, all drivers loaded regardless of 
validity. 


That was the case until recently. On new Macintosh computers, the checksum verification works. 
That's the good news: we've fixed the bug. Now the bad news: this fix causes a number of 
third-party SCSI drivers to fail to load. 


Some SCSI drivers improperly implement the new partitioning scheme. If the partition map entry 
name begins with the four letters “Maci” (case sensitive) and is of type "Apple Driver", the driver 
now has its checksum verified with the entries in the partition map. If this checksum fails, the 
driver is not loaded. This checksum algorithm is documented in Inside Macintosh, Volume V-573, 
The SCSI Manager. 


Drivers That Check In, But Don’t Check Out 


The checksum routine tests the number of bytes specified in pmBoot Size, beginning at the start 
of the driver boot code. Only drivers contained within the new partition map have this test 
performed. If you are using the old partition map scheme documented in Inside Macintosh, 
Volume IV-283, The SCSI Manager, the driver does not have its checksum validated. The 
following is the startup logic in the new Macintosh ROMs: 
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IF 
pmSig = $504D 


pmPartName - Maci 

pmPartType - Apple Driver 

pmBootChecksum = ChecksumOf (bootCode, pmBoot Size) 
Load the driver 

Do not load the driver 


Just When You Thought It Was Safe To Call _SysEnvirons 


The call SysEnvirons was created for compatibility reasons. It allows an application to make a 
single call to the system to determine its characteristics. It keeps the application from reading ROM 
addresses and low memory. This trap is now in the ROM of new machines. But, before you get 
excited about this addition to ROM, there is somethin g that /nside Macintosh, Volume V-5, 
Compatibility Guidelines, states that must be understood by those writing SCSI drivers: 


"All of the Toolbox Managers must be initialized before calling 
SysEnvirons." ..."SysEnvirons is not intended for use by device 
drivers, but can be called from desk accessories." 


This statement means that neither SCSI nor NuBus device drivers can use  SysEnvirons. The 
earliest possible moment to call SysEnvirons is at INIT time. Some SCSI drivers call 
_SysEnvirons, and this causes the Macintosh to crash at boot time. 


To Sum Up 


Check if your partition map is of the version described in the SCSI Manager chapter of Inside 
Macintosh, Volume V, and contains the pmPartName and pmPartType as mentioned earlier in 
this Note. If it does, then verify that the pmBoot Checksum is correct. 1f the checksum is not 
correct, the new Macintosh computers will not load your driver. 


The solution to this problem is to have a valid partition map entry in all cases and to expect the Start 
Manager to perform the checksum verification regardless of the machineType. 
..SysEnvirons is not available until the system has been initialized. 


Further Reference: 


Inside Macintosh, Volume IV-283, The SCSI Manager 

Inside Macintosh, Volume V-5, Compatibility Guidelines 
Inside Macintosh, Volume V-573, The SCSI Manager 
Technical Note #129, SysEnvirons: System 6.0 and Beyond 
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#259: Old Style Colors 
Written by: Rich "I See Colors" Collyer & Byron Han October 1989 


This Technical Note covers limitations of the original Macintosh color model (eight-color) which 
are not covered in Inside Macintosh, Volume 1-173, QuickDraw. 


QuickDraw has always been able to deal with color, just on a very limited basis. Most applications 
have not made use of this feature, since Color QuickDraw-based Macintoshes come with a better 
color model. There are, however, a few nice features which come with the old style color model. 
With the old style colors, it is easy to print color on an ImageWriter with a color ribbon. Another 
advantage is that developers do not have to write special-case code depending upon whether or not 
a machine has Color QuickDraw. 


Now that you are ready to convert to the old style colors, there are a few things you should know 
about which do not work with old style colors. This Note covers the limitations of using old style 
colors, as well as the best ways to work around these limitations. 


Limitations 


The most obvious limitation is that of only eight colors: black, white, red, green, blue, cyan, 
yellow, and magenta. This limitation is only a problem if you want to produce a color-intensive 
application; if this describes your application, then you need not read any further in this Note. 


The next limitation is that off-screen buffers are not very useful. You can draw into off-screen 
buffers, but there is no way to get the colors back from the buffer. This leads into the next 
limitation, which is that CopyBits cannot copy more than one color at a time. 


When you call CopyBits from an off-screen buffer to your window, you need to set the 
forecolor to the color you want to copy before calling CopyBits (i.e., to copy a red object, call 

ForeColor (redColor)). Now when you copy the object, you can only copy one color. If 
you copy different colored objects at one time, then you have a problem. The result of a 
multicolored copy is that all objects copy in the same color, that of the foreground. 


It is possible to work with an off-screen buffer and the old style colors, but it requires a lot of extra 
work. Unless the objects are really complex, then it is probably easier to just draw the objects 
directly into your window. 
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One other limitation does exist. Consider the following code sample. One would assume that this 
sample would work at all times. 


SetPort (myPort); 
savedFG :- myPort^.fgColor; 
ForeColor (redColor); (or any other color) 


{...drawing takes place here...) 


ForeColor (savedFG); 


Surprise. It doesn't always work. The saved value for the fgColor field of the grafPort is 
not a classic QuickDraw color if the grafPort is actually a CGrafPort. If dealing with a 
CGrafPort, the fgColor field actually contains the foreground color's entry in the color table, 
so the second call to ForeColor really messes things up. 


The proper way to set and reset the foreground color with classic QuickDraw's ForeColor call 
is as follows: 


SetPort (myPort); 
savedFG :- myPort^.fgColor; 
ForeColor (redColor); (or any other color) 


(...drawing takes place here...) 


myPort^.fgColor := savedFG; (manually stuff the old fgColor back) 
If (32BQD = TRUE) Then 
PortChanged (myPort); 


This Note also applies to the routine BackColor. 


What Works 


The easiest way to work with these limited colors is to use pictures. When you draw the images, 
you should draw into a picture. Then when you want to draw the images into your window or to a 
printer, call DrawPicture. Pictures work well with the old style colors, and you don't need to 
worry about making sure that the forecolor is current when you draw into your window. 


Once you have the picture, you can use it to draw into the screen or to the printer port. You can 
also set the WindowRecords windowPic to equal your PictureHandle so updates are 
handled by the Window Manager. 


Further Reference: 


Inside Macintosh, Volume 1-173, QuickDraw 
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#260: NuBus Power Allocation 
Written by: Rich “I See Colors” Collyer October 1989 





This Technical Note discusses a very real power limit for NuBus™ expansion cards and warns 
developers to heed this limit lest they want users trashing their machines by overextending the 
Macintosh power supply. 


Click-Click Mode? 


Designing Cards and Drivers for the Macintosh clearly states that allowed power per NuBus slot is 
13.9 watts (pg. 6-6). That is 2 amps at 5 volts, 0.175 amps at 12 volts, and 0.15 amps at -12 
volts. If your Nubus card requires more than this allocation, then you need to make sure that users 
do not fili all of their Nubus slots. A good rule of thumb is that if users can fill all of their slots 
with your card and the machine is still able to boot, then you are okay. If the machine goes into 
click-click mode, then you need to make sure that users cannot fill their slots. Click-click mode is a 
safety feature of the Macintosh power supply. The Macintosh is trying to start the machine and 
finding that the power requirements are greater than it can handle. The problem is that the power 
supply is not getting far enough into the startup procedure to turn itself off, so it keeps trying to 
tum itself on. The only way out of this mode is to pull the plug. 


What's Allowed and Why 


Following are a few scenarios which might cause major heart problems for a user (these stories are 
fictional, and the names have been made generic to protect the innocent). 


Slot Card Power Requirement 
9 video card 10 watts 

A EtherTalk 10 watts 

B memory card 20 watts 

C AtoD 15 watts 

D CPU 20 watts 

E video card 10 watts 

Total 85 watts 


This first scenario ends with a power requirement which exceeds the allowed power by 1.6 watts. 
The result of this over requirement can cause some very nasty results. Even if the machine could 
work, there is no guarantee to cover a thermal problem. The Macintosh was designed with the 
assumption that there would only be a need to dissipate 83.4 watts of NuBus power. If the 
machine must dissipate more than 83.4 watts of NuBus power, then it is possible that you might 
start burning chips. 
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An even worse scenario considers a fully loaded Macintosh IIcx. It is a lot easier to load up a IIcx, 
since the IIcx has half as many slots as the II and a power limit of 41.7 watts. This second 
scenario demonstrates a less high-powered user with a IIcx. 


Slot Card Power Requirement 
9 32-bit video card 15 watts 

A video card 10 watts 

B CPU 20 watts 

Total 45 watts 


In the second case, the machine is overdrawn by 3.3 watts. You may think that this is not a 
reasonable list of power requirements, but the reality of the power requirements is not the point. 
The point is that card developers must put forth an effort to protect the users, or we all look very 
bad when the silicon starts to melt. It is not very favorable to have our users burning up their 
machines because a NuBus card needed more power than it was allowed. 


The wattage which a card requires is not the entire problem. It is possible to stay within the 13.9 
watt limit and still have problems. You must also stay within the amperage limit for each voltage. 
You cannot just assume that since you are not using the 12 and -12 volts that you can use 2.78 
amps of 5 volts (13.9 watts); the Macintosh power supply was not designed to convert 12 volt 
power allocation to 5 volt when it is needed. Scenario three presents an example of a Macintosh I 
which 4s filled with cards that are within the wattage limit, but that exceed the amperage limit. 


Slot Card 5 Volt Power Requirement Amps 
9 video card 10 watts 2 

A EtherTalk 10 watts 2 

B memory card 13.9 watts 2.78 
C AtoD 13.9 watts 2.78 
D CPU 13.9 watts 2.78 
E video card 10 watts 2 


Total 71.7 watts 14.34 


Under normal conditions, the Macintosh II power supply can handle up to 12 amps at 5 volts. In 
the third scenario the NuBus cards are drawing 14.34 amps. Half of the cards are within the limit, 
but the other cards are not, and the result is a Macintosh which goes click-click. 


But I Need the Power... 


Now that we've told you not to take more power than you are allowed, we are going to give you a 
way out. We understand that it is impossible to fit within this power budget with some types of 
NuBus cards; if your card contains a processor, or worse, a lot of RAM, then you are going to run 
into the power allocation very quickly. In the rare case when you do need to consume the power of 
multiple slots, then you really must make absolutely sure that the slot or slots next to your card are 
not used. 


The first possible solution is simply blocking off the slot or slots next to your board. You can 
build a device which extends out of your card to prevent the user from inserting other cards in the 
the adjoining slot or slots. The first slot to cover is the one on the component side of your card, 
thus allowing increased air flow on the side of your card which is most likely a little warm. This 
method, however, is not necessarily the method of choice. One of the problems with this method 
is that the power allocation is not part of the NuBus specification, it is a Macintosh-specific limit. 
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It is always possible that this limit will be raised on future machines, and you do not want to 
implement this solution on machines where the problem is not a problem. The second solution is a 
bit cleaner than the first; however, it also has the potential for a similar problem with future 
machines. 


The second solution is to design your card as a multiple-card implementation and have an internal 
bus which connects the two cards with ribbon cables or another type of connector. The benefits to 
this solution are a guarantee that users physically cannot put more cards in their systems than the 
power supply can handle and you get additional real estate with which to play. 


A third, and perhaps simpler, solution is to ship a slot cover with your card. You can ask users to 
install the cover over the slot next to your card (or multiple slots if necessary). This cover should 
keep the user from inadvertently using the slot while not forcing the loss of a slot in any future 
machine with an increased power budget. This route would require an explanation and visible 
warning in the documentation; however, if the users do not heed your warning, then they cannot 
very well blame you for their clicking Macintosh (they will probably blame us). 


These solutions are not the only ones which exist, but we haven't thought of any other great ideas. 
The main goal is to provide a method which protects users from overextending their machines. If 
you can devise such a method, then more power to you (well, not really). 


Don't Get Flamed 


So the moral (what's that) of the story is that you need to put yourself into the shoes of your users 
(but don't try it literally). If they burn up our computers or find themselves in click-click mode 
because a NuBus card got a little greedy, then they are going to be very upset, and that is 
something that both Apple and third-party developers need to work very hard to prevent. If you 
“need” the extra power, then you must make absolutely sure that users are not going to get burned 
by your NuBus card. 


Further Reference: 
+ Designing Cards and Drivers for the Macintosh 
¢ IEEE Standard for a Simple 32-Bit Backplane Bus: NuBus 
e Technical Note #234, NuBus Physical Designs—Beware 


NuBus is a trademark of Texas Instruments 
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#261: Cache As Cache Can 
Written by: Andrew Shebanow October 1989 
This Technical Note documents some new traps for manipulating the data and instruction caches on 


68030-based Macintosh models and describes the MMU mapping set up by the ROMs for 
NuBus™ cards. 





The Motorola MC68030 CPU used by the Macintosh IIx, IIcx, IIci, and SE/30 includes a data 
cache, an instruction cache, and a MMU (Memory Management Unit). This Note describes the 
problems that data caching can cause, Apple's solution to this problem, and additional information 
about MMU mapping on MC68030-equipped machines. 


Stale Data (Baked Fresh Daily) 


Designing Cards and Drivers for the Macintosh II and SE, which was written before these 
machines were released, states: 


"Future systems may implement data caching (based upon the MC68030, for 
example). To support this, RAM-like cards should always supply ail 32 bits, 
regardless of the NuBus request... 


Note that caching of data can be controlled by software; that is, some address 
spaces can be declared non-cacheable. Any card that is not capable of supporting a 
full 32-bit read must have its corresponding driver software set up the caching 
control appropriately." 


Data caching can be a problem if you are working on a system with multiple bus masters, since you 
can get stale data. Following is an example of a situation where the problem occurs. 


Lets say that you have a whizzy disk controller card that supports DMA. The board reads 
command buffers from the main CPU's memory area and writes status information back to the 
command buffer when done. Before the command is started, the 68030 sets up the command 
buffer and zeroes the status code (the following figures are not to scale). 
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Expansion Card 





Figure 1-Write Through Cache 


At this point the cache and the memory both contain the value 0, since the 68030's cache is 
write-through (that is, it always writes data to memory immediately). Now the 68030 starts the 
command running and waits for an interrupt from the disk controller card. It then reads back the 
status from the command buffer. 


MC68030 





Figure 2-Read From Cache 


Oops! Because the status code's value was already in cache, the 68030 thought that the status was 
0, even though the actual value in memory was -23. This type of thing can cause some very 
hard-to-find bugs in your driver. Fortunately, Apple provides some traps which let you flush the 
data and instruction caches without using privileged instructions (which is, as you should all know 
by now, a major no-no). 
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Note: The MMU allows pieces of memory to be marked non-cacheable. All 68039 
Macintoshes turn off data caching for all address areas which are not designated as 
RAM or ROM space in the memory map. What this means in practice is that you 
never need to worry about the stale data problem in reverse: the CPU won't cache 
data stored on NuBus cards. 


Following are the interfaces for these calls, for MPW Pascal and C (respectively): 


FUNCTION SwapInstructionCache(cacheEnable: BOOLEAN): BOOLEAN; 
pascal Boolean SwapInstructionCache(Boolean cacheEnable); 


This call enables or disables the instruction cache according to the state passed in cacheEnable 
and returns the previous state of the instruction cache as a result. 


PROCEDURE FlushInstructionCache; 
pascal void FlushInstructionCache (void); 


This call flushes the current contents of the instruction cache. This has an adverse effect on CPU 
performance, so only call it when absolutely necessary. 


FUNCTION SwapDataCache(cacheEnable: BOOLEAN): BOOLEAN; 
pascal Boolean SwapDataCache (Boolean cacheEnable); 


This call enables or disables the date cache according to the state passed in cacheEnable and 
returns the previous state of the data cache as a result. 


PROCEDURE FlushDataCache; 
pascal void FlushDataCache (void); 


This call flushes the current contents of the data cache. This has an adverse effect on CPU 
performance, so only call it when absolutely necessary. 


Note: Before you call any of these routines, make sure that the HWPriv ($A198) trap is 
implemented, or your program will crash. 


These calls are provided as part of the MPW 3.1 library. For those of you without MPW 3.1, you 
can use the following MPW assembly-language glue: 


CASE OFF 


_HWPriv OPWORD $A198 


SwaplnstructionCache PROC EXPORT 
MOVEA.L (A7) £, Àl : save return address 


MOVEQ #0,D0 ; clear DO before we shove Boolean into it 
MOVE.B (A7) +, DO ; DO <- new mode 
MOVE.L DO, AO ; _HWPriv wants mode in AO 
CLR.W DO ; set low word to O (routine selector) 
.HWPriv 
MOVE.W AO, DO : move old state of cache to DO 
TST.W DO ; if non-zero, cache was enabled 
BEQ.S WasFalse ; if zero, leave result false 
MOVEO #1,DO ; set result to true 
WasFalse: 
MOVE.B DO, (A7) ?; save result on stack 
JMP (A1) 
ENDPROC 
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FlushInstructionCache PROC EXPORT 


MOVEA.L (A7) H,A1 ; save return address 

MOVEO #1,DO : set low word to 1 (routine selector) 
 HWPriv 

JMP (A1) 

ENDPROC 


SwapDataCache PROC EXPORT 
MOVEA.L (A7) *, Al ; save return address 


MOVEO #0,D0 : clear DO before we shove Boolean into it 
MOVE, B (A7) *, DO ; DO <~ new mode 
MOVE.L — D0,A0. ; _HWPriv wants mode in AO 
MOVE,W #2,D0 ; set low word to 2 (routine selector) 
_HWPriv 
MOVE.W AO, DO ; move old state of cache to DO 
TST.W DO ; lf non-zero, cache was enabled 
BEQ.S WasFalse ; if zero, leave result false 
MOVEO #1,D0 ; set result to true 
WasFalse: 
MOVE.B DO, (A7) ; Save result on stack 
JMP (A1) 
ENDPROC 


FlushDataCache PROC EXPORT 


MOVEA.L (A7) *, A1 ; save return address 

MOVEQ #$3,D0 ; set low word to 3 (routine selector) 
 HWPriv 

JMP (A1) 

ENDPROC 


Further Reference: 
¢ Inside Macintosh, Volume V, Operating System Utilities 
* Designing Cards And Drivers for the Macintosh II and SE 
e  SEI30 Developer Notes (APDA) 


NuBus is a trademark of Texas Instruments 
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#0: About Macintosh Technical Notes October 1989 





Technical Note #0 (this document) accompanies each release of Macintosh Technical Notes. This 
release includes revisions to Notes 129, 161, 176, 184, 193, 196, 206, 221, 238, 244, 247-249, 
and 252-253, new Notes 254-261, and an index to all released Macintosh Technical Notes. If 
there are any subjects which you would like to see treated in a Technical Note (or if you have any 
questions about existing Technical Notes), please contact us at one of the following addresses: 


Macintosh Technical Notes 
Developer Technical Support 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 75-3T 
Cupertino, CA 95014 

AppleLink: MacDTS 

MCI Mail: MacDTS 


We want Technical Notes to be distributed as widely as possible, so they are sent to all Partners 
and Associates at no charge; they are also posted on AppleLink in the Developer Services bulletin 
board and other electronic sources, including the Apple FTP site (IP 130.43.2.2). You can also 
order them through APDA. As an APDA customer, you have access to the tools and 
documentation necessary to develop Apple-compatible products. For more information about 
APDA, contact: 


APDA 

Apple Computer, Inc. 

20525 Mariani Avenue, M/S 33-G 
Cupertino, CA 95014 

(800) 282-APDA or (800) 282-2732 
Fax: (408) 562-3971 

Telex: 171-576 

AppleLink: APDA 


We place no restrictions on copying Technical Notes, with the exception that you cannot resell 
them, so read, enjoy, and share. We hope Macintosh Technical Notes will provide you with lots 
of valuable information while you are developing Macintosh hardware and software. The 
following pages list all Macintosh Technical Notes that have been released (both by number and by 
subject). 
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#176: Macintosh Memory Configurations 


Revised by: Craig Prouse & Dennis Hescox October 1989 
Written by: (Cameron Birse November 1987 


This Technical Note describes the different possible memory configurations of all models of the 
Macintosh family that use Single Inline Memory Modules (SIMMs) as well as the non-SIMM 
memory upgrade options of the Macintosh Portable. Special thanks to Brian Howard for the 
Macintosh Plus and original SE drawings, and for the inspiration for the other drawings. 

Changes since April 1989: Added configurations for the Macintosh IIci and Macintosh 
Portable and a section describing special problems relating to the use of four megabit (Mbit) DRAM 
SIMMS in the Macintosh II and IIx. 


Macintosh Developer Technical Support receives numerous questions about the many different 
possible configurations of RAM on the different Macintoshes, so we'll attempt to answer these 
questions in this Technical Note, as well as provide a showcase for some outstanding artwork by 
Apple engineer Brian Howard. 


Warning: Because the video monitor is built in, there are dangerous voltages inside the 
cases of the Macintosh Plus and Macintosh SE computers. The video tube 
and video circuitry may hold dangerous charges long after the computer's 
power is turned off. Opening the case of the Macintosh Plus and Macintosh 
SE computers requires special tools and may invalidate your warranty. 
Installation of RAM in the SIMM sockets in these computers should be done 
by qualified service personnel only. 


Macintosh Plus 
The Macintosh Plus has the following possible configurations (see Figure 1): 


512K, using two 256 Kbit SIMMs 

1 MB, using four 256 Kbit SIMMs 

2 MB, using two 1Mbit SIMMs 

2.5 MB, using two 1Mbit SIMMs and two 256Kbit SIMMs 
4MB, using four 1Mbit SIMMs 


It is important to place the SIMMs in the correct location when using a combination of SIMM sizes, 
as in the 2.5 MB example, and to make sure the right resistors are cut. Refer to Figure 1 for the 
correct location of the SIMMs and size resistors. 
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(SIMMs must be 120 nS RAS -access time (SIMMs must be 80 nS RAS-access time 
or faster, and the same speed within a row.) or faster, and the same speed within a row.) 


Macintosh IIcx memory configurations are 
identical to the II, IIx, and SE/30. 





Figure 5-Macintosh IIcx, Ici, and Portable Memory Configurations 





System Memory Size: 512K 
SIMMs Configuration 
Row 1 (SIMMs 1 & 2): 256K 
Row 2 (SIMMs 3 & 4): — Not Installed 
RAM SIZE Resistors 
256 Kbit (R8): 150 Ohms 
One Row (R9): 150 Ohms 
System Memory Size: 1 MB 
SIMMs Configuration 
Row 1 (SIMMs1&2) 256K 
Row 2 (SIMMs 3 &4): 256K 
RAM SIZE Resistors 
256 Kbit (R8): 150 Ohms 
One Row (R9): Not Installed 
System Memory Size: 2 MB 
SIMMs Configuration 
Row 1 (SIMMs 1 & 2): 1MB 
Row 2 (SIMMs 3 & 4). Not Installed 
RAM SIZE Resistors 
256 Kbit (R8): Not Installed 
One Row (R9): 150 Ohms 
System Memory Size: 2.5 MB 
SIMMs Configuration 
Row 1(SIMMs 1&2): 1MB 
Row 2 (SIMMs 3 & 4): 256K. 
RAM SIZE Resistors 
256 Kbit (R8): Not Installed 
One Row (R9): Not Installed 
System Memory Size: 4 MB 
SIMMs Configuration 
Row 1(SIMMs1&2): 1MB 
Row 2 (SIMMs 3 & 4) 1MB 
RAM SIZE Resistors 
256 Kbit (R8): Not Installed 
Lid bod ad d. One Row (R9): Not Installed 
(SIMMs must be 150 nS RAS-access time or faster, and the same speed within a row.) 
Figure 1-Macintosh Plus Memory Configurations 
Row 1 (SIMMs 1 & 25 1 MB 
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SIMMs Configuration 
Row 1 (SIMMs 1 & 2) 
Row 2 (SIMMs 3 & 4) 


RAM SIZE Resistors 
256 Kbit (R35) 
One Row (R36) 


System Memory Size 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2) 
Row 2 (SIMMs 3 & 4) 


RAM SIZE Resistors 
256 Kbit (R35) 
One Row (R36) 
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SIMMs Configuration 
Row 1 (SIMMs 1 & 2) 
Row 2 (SIMMs 3 & 4) 


RAM SIZE Resistors 
256 Kbit (R35) 
One Row (R36) 


System Memory Size 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2) 
Row 2 (SIMMs 3 & 4) 


RAM SIZE Resistors 
256 Kbit (R35) 
One Row (R36) 


System Memory Size 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2) 
Row 2 (SIMMs 3 & 4) 


RAM SIZE Resistors 
256 Kbit (R35) 
One Row (R36) 


(SIMMs must be 150 nS RAS-access time or faster, and the same speed within a row.) 


Figure 2-Macintosh SE Memory Configurations 
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Macintosh II, IIx, and Macintosh SE/30 
memory configurations are identical. 
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System Memory Size: 1 MB System Memory Size: 2 MB 
Bank A: 4 x 256K SIMMs Bank A: 4 x 256K SIMMs 
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System Memory Size: 4 MB System Memory Size: 5 MB System Memory Size: 8 MB 


Bank A: 4 x 1 MB SIMMs Bank A: 4 x 1 MB SIMMs Bank A: 4 x 1 MB SIMMs 
Bank B: Empty Bank B: 4 x 256K SIMMs Bank B: 4 x 1 MB SIMMs 


Figure 4-Macintosh SE/30, II, and IIx Memory Configurations 


System Memory Size 512K 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2): Not Installed 
Row 2 (SIMMs 3 & 4): 256K 


Jumper on 2/4M 


System Memory Size 1 MB 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2): 256K 
Row 2 (SIMMs 3 & 4): 256K 


Jumper on 1M 





System Memory Size 2 MB 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2): Not Installed 
Row 2 (SIMMs 3 & 4): 1 MB 


Jumper on 2/4M 


System Memory Size 2.5 MB 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2): 256K 
Row 2 (SIMMs 3 & 4): 1MB 


Jumper off 


System Memory Size 4 MB 


SIMMs Configuration 
Row 1 (SIMMs 1 & 2): 1 MB 
Row 2 (SIMMs 3 & 4) 1 MB 


Jumper off 





(SIMMs must be 150 nS RAS-access time or faster, and the same speed within a row.) 
Figure 3-Macintosh SE (with jumper) Memory Configurations 


Macintosh SE 


The Macintosh SE configurations (the original motherboard as well as the revised motherboard 
with a memory jumper selector) are the same as the Macintosh Plus, except physical locations on 
the motherboard are different. In addition, memory configurations with only two SIMMS (e.g., 
512K and 2 MB) use slots 3 and 4 on the revised SE motherboard instead of slots 1 and 2 like the 
original motherboard and Macintosh Plus. Refer to Figures 2 and 3 for the correct locations and 
settings. 


Macintosh SE/30, II, IIx, and IIcx 


Since these machines use a 32-bit data bus with eight-bit SIMMs, you must always upgrade 
memory in four SIMM chunks. The eight SIMM connectors are divided into two banks of four 
SIMM slots, Bank A and Bank B. 


On the Macintosh SE/30, Bank A is located next to the ROM SIMM while Bank B is next to the 
68882 co-processor. On the Macintosh II and IIx, Bank A is the bank closest to the edge of the 
board, while on the Macintosh IIcx, Bank A is the bank closest to the disk drives and power 
supply. Refer to Figure 4 for the proper locations of Banks A and B on the SE/30, II, and IIx, and 
refer to Figure 5 for the proper locations on the Ilcx. 


Unlike the Macintosh Plus and the Macintosh SE, these machines have no resistors to cut and no 
jumpers to set; you need only install the SIMMS in the correct banks and you'll be up and running. 
You can implement the following configurations: 


1MB, using four 256 Kbit SIMMs in Bank A 

2MB, using eight 256 Kbit SIMMs in Banks A and B 

4MB, using four 1 Mbit SIMMs in Bank A 

SMB, using four 1 Mbit SIMMs in Bank A and four 256 Kbit SIMMs in Bank B 
8MB, using eight 1 Mbit SIMMs in Banks A and B 


Again, it is important to make sure the right size SIMMs are in the right Bank; when you are using 
a combination of SIMMS, the larger SIMMS (in terms of Mbits) must be in Bank A. When you are 
using only four SIMMs, they must be in Bank A as well. 
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Macintosh IIci 


The Macintosh IIci motherboard layout is somewhat different from the IIcx, but the location of the 
RAM SIMMs is unchanged. Bank A is still the bank closest to the disk drives. Refer to Figure 5 
for the proper locations of Banks A and B on the IIci. 


The IIci has a much-improved RAM interface and allows a great deal more freedom when installing 
SIMMs. Banks A and B are interchangeable, meaning that when mixing two sizes of RAM, the 
larger SIMMs do not necessarily have to go in Bank A. In fact, for best performance when using 
on-board video, Apple recommends that the smaller SIMMs be installed in Bank A. Note, 
however, that if on-board video is used, then RAM must be present in Bank A. 


The IIci requires that SIMMs be 80 ns RAS-access time or faster and the same speed within a 
row. You can implement the following memory configurations with 256K and 1MB SIMMs: 


1 MB using four 256 Kbit SIMMs in Bank A or in Bank B 

2 MB using eight 256 Kbit SIMMs in Banks A and B 

4 MB using four 1 Mbit SIMMs in Bank A or in Bank B 

5 MB using four 256 Kbit SIMMs in Bank A and four 1 Mbit SIMMs in Bank B 
5 MB using four 1 MBit SIMMs in Bank A and four 256 Kbit SIMMs in Bank A 
8 MB using eight 1 Mbit SIMMs in Banks A and B 


The 1 MB and 4 MB configurations using only Bank B are not compatible with on-board video, 
since Bank À must contain memory when using on-board video. The first 5 MB configuration 
(with 256 Kbit SIMMs in Bank A) is recommended for 5 MB configurations using on-board 
video. 


Parity RAM 


Some specially-ordered versions of the Macintosh IIci are equipped with a PGC chip and support 
parity for RAM error detection. These machines require parity RAM. SIMMS for these machines 
are nine bits wide instead of eight, so there is generally an extra RAM IC on the SIMM. There is 
no difference in the installation of 256K x 9 or 1M x 9 SIMMs. 


Macintosh Portable 


Memory expansion on the Macintosh Portable is different from other members of the Macintosh 
family since the Portable uses memory expansion cards in place of SIMMs. The base Portable is 
equipped with 1 MB of RAM on the motherboard and has one RAM expansion card slot. Apple 
currently supplies a 1 MB memory expansion kit which takes the Portable to 2 MB total. Apple 
and third-party developers may produce higher capacity expansion boards (2 MB to 8 MB) in the 
future. 


Since the Portable has only one RAM expansion slot, you may use only one memory expansion 
board at a time. This limit means that a 1 MB expansion board would have to be completely 
replaced by a higher capacity board when it became available. 


Total RAM for the Portable will always be 1 MB plus the size of your one RAM expansion board 
(if installed). Refer to Figure 5 for the location of the RAM expansion slot. 


—€— —— "-— —————— —————À——H————Á!À Q)"Í 
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4 Mbit DRAMS in Revolt 


When the Macintosh II was originally designed, Apple engineers intended for it to accept large 
amounts of memory in the form of 4 MB and 16 MB DRAM SIMMS. That was in 1986, when 1 
Mbit DRAM was difficult to find and the higher-density chips did not yet exist. The engineers 
anticipated the pinouts of the yet-to-be introduced 4 MB SIMMs and provided all the necessary 
hardware and address multiplexing to allow installation of these parts when they became available. 


Woe that Cupertino is not Camelot, James Brown is in jail, and 4 MB SIMMs do not work as 
advertised in most cases. This is the story of the Revolt of the 4 MB DRAM SIMMs. 


Preliminary Notes 


Before diving into the problem with 4 Mbit DRAMS, there is some preliminary ground which must 
be covered. 


First, there are a couple ways to construct a 4 MB SIMM. Using old technology, it is possible to 
cram together 32 DRAM ICs of 1M x 1 density. Using new technology, it only takes eight 4M x 1 
ICs, resulting in a much smaller, lower-power module. If a 4 MB SIMM is of the large, so-called 
composite type (i.e., it is constructed of thirty-two 1 Mbit ICs), then everything is fine except on 
the original Macintosh II. 


This exception is due to an undocumented feature in the ROM firmware shipped with the original 
Macintosh II. Unfortunately, the original Macintosh II ROM startup code does not know about 4 
MB SIMMs and dies a horrible death before the cursor even appears. Thus, a Macintosh II with 
original ROMs is limited to using 1 MB SIMMs and 8 MB RAM maximum. Subsequent 
Macintosh models have revised ROMs which recognize 4 MB SIMMs. 


A Macintosh II CPU can receive a ROM upgrade enabling it to accept 4 MB SIMMs. This upgrade 
requires installation (strangely enough) of the 1.4 MB SuperDrive package. This requirement is 
presumably because the SuperDrive package includes the Macintosh IIx ROMS, which can handle 
4 MB SIMMS, but which also expect the presence of a SWIM chip in place of the old IWM. 


With the SuperDrive upgrade, the Macintosh II is on equal footing with the Macintosh IIx. That is, 
SIMMs made exclusively of the new 4 Mbit ICs still won't work, regardless of whether you are 
using a Macintosh II or IIx; therefore, for the remainder of this discussion, Macintosh II is used to 
refer to not only the original Macintosh II, but also the IIx. 


The 4 Mbit Problem 


DRAM ICs are now available in 4 Mbit density, but they come with a very nasty surprise. JEDEC, 
the committee overseeing the standardization of new solid-state devices, has added an additional 
built-in test mode to high-density DRAMs. The test mode is invoked by a sequence of electrical 
signals which was ignored by earlier-generation DRAM. The crux of the situation is this: under 
certain conditions, the Macintosh II unwittingly activates this new test mode and large amounts of 
memory become very forgetful. 


More Specifically... 


Those who are interested in the specific phenomenon occurring within the memory ICs should 
consult the detailed technical data supplied by the DRAM manufacturers. This Note only explains 
how the Macintosh II offends this new feature of the 4 Mbit DRAM, and hence, what might be 
done to work around the problem. 





#176: Macintosh Memory Configurations 9 of 10 


The Macintosh II uses /CAS-before-/RAS refresh cycles to keep RAM up-to-date on its contents. 
For 1 Mbit DRAM, the state of the /W control line is ignored during this type of refresh cycle. No 
longer. DRAM of the 4 Mbit variety goes off into test mode if /W is asserted (low, so that the 
RAM thinks it is write-enabled) during a /CAS-before-/RAS refresh cycle. The problem with the 
Macintosh II is that /W is the same signal as the MPU R/W line, and if the MPU is writing to an 
VO address or a NuBus™ card concurrently with a refresh cycle, all the conditions are right for a 
waltz into test mode. Unfortunately, this condition is not all that unusual, since video card 
accesses qualify. 


The Salvage Process 


All is not necessarily lost, and although the situation is ugly, there is still a way to use 4 Mbit 
DRAM ICs to construct 4 MB SIMMs which work in the Macintosh II. A solution lies in the 
addition of a ninth IC to the SIMM. Programmed with suitable logic, a high-speed (-D or -E 
suffix) PAL'M on the SIMM itself can recognize and intercept /CAS-before-/RAS refresh cycles 
and set /W appropriately before any damage is done. More or less, the PAL becomes an intelligent 
buffer between the MPU read/write line and the DRAM write-enable lines. When the PAL senses a 
refresh cycle commencing, it holds /W high, ensuring that the ICs are not corrupted by the 
potentially dangerous processor-generated R/W signal. 


What the Future Holds... 


It is unlikely that Apple will recall the affected machines to install a fix or even change the design of 
current-model Macintosh II computers produced in the future. New members of the Macintosh 
family should correct the problem, however. Note that the Macintosh SE/30, IIcx, and Ilci all 
address this problem. There are currently no specifications available for 16 Mbit DRAM; therefore, 
it is unknown at this time whether any current Macintosh models will be compatible with these 
devices. 


Consolation for SIMM manufacturers: SIMMs constructed with an on-board PAL are not 
necessarily Macintosh II-specific. SIMMs constructed in this manner should work without 
modification in any application calling for 4 MB SIMMS (except in the unlikely event an application 
requires the new test mode). 


Further Reference: 


e Inside Macintosh, Volume V-1, Compatibility Guidelines 
* Guide to Macintosh Family Hardware, Chapter 5, Macintosh Memory 


NuBus is a trademark of Texas Instruments 
PAL is a trademark of Monolithic Memories, Inc. 
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TOOLBOX sacs rere e Ve ise cerca rend cea Ee viet vas 227, 229 
OPS ee N EE ie So UO UTE Ta EE 186 
TPEIDIg.a ee Ee Ee GR EORR E DE ee ee 95 
trackceaclie o SE ee seat id GN qnd 81 
TrackBOR TERNI 79 
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transaction ID validity ...................... eene 250 
TRAP os if erre o ux ed epe e UR EE Mu 2 
irap "IDICITaCe oen itae rii do TS EE oan 221 
trap Date his oh EV De ie 25, 212 
TRE Timer i. iss etie e Ge ee eg GE UNA ee ar av» 250 
dE IA EE TIN 239 
EXPODE Se berto NW vis epit t ed 242, 245 
undocumented.................... neos eee eoe nene nenne rena oun oo 227 
ie OB AO cp exer ee Feet aS ve EE RN EA FOSSE ERREUR 215 
Unimplemented......................... eere ee 156 
did IE N i rh EE EI 198 
unit attention eise ge o di e De vx ee Eg Eb dee 96 
ALA Ee GE N ES EE OO Se Sous dst 71 
|» cM 229 
MIN QE ——————eemt 88 
Uie. iii ose E EE AO PR ERE 221 
update switching ...........n.seeossssensseasesesreresesssasrere 180 
UpdateResFile ....../ iiie te Oei ett har rne 116, 188 
upgrading memory............... esee 176 
user MOINS ciis vc ee EO F rores von ko ub ddl duke Magd Vu An MUR o bei 34 
user stack pointer .............. eese nnne 2 
User-Interface Thought Police............................-- 180 
userTIGm: is io cei ee ean Cap eu erns T Toe uie AE 203 
Bo cie EE EE EE SE pe VH T CHE Tdi d 2 
ÜTableBase........ eicecuno eve eio ke dk eua noo Yer eoa n6? 250 
VBL interrupts.................... eeeeee eren eee nennen 221 
VBL Uo oe e AUR DATAS OE eee eers 180 
VCB QUOC ————————€——ÓÀ 24, 44 
vcbDRefNum soe dese we ese oe Ge see de SN de Re SR ee kk de 106 
VCDDEVNDID sessie ow SEE oe N GESE Sk De PE ee ee 106 
verify flag indicator byte.................... eere 225 
verifyFlag esse ees sooo sesse ee eene EE ORE e seta ean a aan 225 
MeFSIOf octies nord oe vae ae una e a pn Pea qe In EG 189 
versionRequested ...................... eee eene 129 
Verskeie. sesse iE au ER ONE GEE Ve MERE N CA GE RE VE ge 189 
VersRecHandle............cccccsccssarscssccessosescsscccaconans 189 
VErsRacPif... es oes eieies des ss N ee eg eie ou ke 189 
VIA secedere Ge ie se iN ee Lese ed 2 
VIA BE GE SE rocas ee isse ee E veia ED 117 
video buffer... sesse oe era br eoa e ee na xo de bek ee pa Re ede Ed 2 
videoEard ES EE DE chee De TAN CU eg Ke Neg ek Ged 144 
VIEWRÓCU;.. sire esa NE OE KA Fa ed VERRE NU 82 
viral infection 11.1. eco ae et e da rre tne Ke KS pha ve ov Ed 231 
virtual key code ees EE ARE Uie Ne s 229 
virtual MEMOFY.... esse sees sees ee eene DRR AA Pe EGO area 203 
VISREIL Ee e HUP anie 194 
VODUITIG. ordeo a deo re wien ap E edo yer obey GEREED MA 24, 106 

GEE iir veo yr DR EFE EG PASE Fa COH Ere gee 106 
VReENUD sio poor orga bu Se bie Ke 44, T1, 126, 238 
WaitMouseUDp ......... eee e e ee oret ata raa ED GOGGA GEE ee 194 
WaitNextEvent .............. eere 158, 177, 194 
hr cru M — 176 
WDER PTT EC 126 
bib N AE IN 212 
WEYERS SE ER ani vv ek bl ee dS 72 
WDP D. Ed ENE Ee adni Vr eeu VER ha 126 
WOREENUM, ccccsissisccscnctsccervesecsescccsccctedccesssens 44,77 
WDRefNum es SG ee EG RS Rd De ee ee De de 126 
Width table ee veo n OG ERR Ee Di ee oge Ee Si 92 
Window Manager .... eis sesse ee see enm nee 203 
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ase EE EE iue po esa 53, 194 
word-break table ........................ eee eere eerte 182 
working directory ................ sees 44, 77, 126, 190 
Working Directory Control Block......................... 126 
working directory ID ................... eene 238 
RE EE N EA eee 187 
WHIELIAP NE n sov RE ARAS OE TERR EXE HE VA 250 
WriteResource ......... eee ee eee eee eene nera etna 111, 188 
XCMD SR EE tootsie tun ee 256 
Ee EER EE s Res P EE 229 
XDWEY E E OE IE 229 
vA) Tr^ 9, 250 
zone information protocol......................... Fe 9, 250 
ZOOMREEL es Ese seed ura Vua eoe OUR CERE EU 194 
Zoom WindOW. sie iaseveso eN ge va aa drea a aoo e de 79 
SADBOD: citi EE NE Te ge eso dd 206 
ADBRelrit... es arre re REX RR ERG apri SESS 206 
E E 248 
ie REPE 248 
BIS At poete ter eO Deed EA Ge El ee Ge Ee 248 
Cale Mask. ER EE EE EG DADO CERE VV 193 
6 AE EE DE RE 126, 180 
Bl G15) (0) 74 6) EE 229 
_CopyBits oi ee Ee Ge ES ed ie Ee Vd 120, 252, 259 
 CountADBS.. «es eiere rias ke sesde sesse dd dd ge Ged 206 
DRIE ys saad cise ncaa ed ee N ev S RA ge se ey 93 
 DialogSelect................... eee AA EA EFES PAGE 251 
Drag GTayREn. sissies ee eed Ó 193 
Drag TREREN esse oes ees SE SPEED EE SE RE Re no 247 
Me ged ME EE 259 
Nr cV" ee ee Se Veg dd dd 180 
E rie MR 242 
Bos AR EE c eb sd oe don eue chari rene Yoh 242 
Bo £s m ————— € 259 
Eje m €—Ó——— 246 
Bold ce 246 
 GetCPixel....... eter aono in rea e rto de noh rn rho No odas 229 
GEE Table. UA 244 
BIST IECIT II 243 
GetIndADB.... iese ep ken aman er ra ina SG adve 206 
GetNextEvent ............ eee neenon 180, 205 
Get RESOUICE..iioicio eroe oed DE Doo dee Vee v TEE Eqs eN ed 228 
Get WDInfOo. coii i eere EE N IA A ROSE odds Dee 229 
GetWRefCOn.... recess dese py ie GE Ua Ge dAX aad ae sux vs 227 
[AVAL MP 248 
_HandleZone Lei N vL Fete OLEI EY ATE VA 248 
Rot GT ii eee area toa ied eben 227 
Hide DIDI esse Ee Re E Ge ee se Ee de 251 
By: AE RR EE 261 
Index2ColoF... sisie sedes dd Ee GEE ee 229 
Elle OE EA OE RE ARES 223 
DEW de AE EE IM 247 
MT. AREA NE EE EE 193 
Intl SOLID SE EE ee nag» 242 
AE. AE c yo YER HERR EE 126, 180, 205 
Local T6Global. EE SERS SERE INR de ida 120 
MaxBlock EE OE EO EE NER 229 
Metri Sela. re ss care e see ee EG rp ed 180 
MEMemTOD: ies eee tne ees sesse en eed de Ee ds 205 





 MFTempNewHandle ........ sees ss se RR RR ER 205 
— MFTopMetm..............eeee eee eee eee eee eene enano aae aaa ues 205 
ModalDileg.. coner rg pr nm ne cia vie ern 248 
 NewHandle ;.;.« oes oek Ke ed sk eg dee 205, 233 
NewWwRgll.. OE EO sa pa enn 193 
NGetTrapAddress............... eee eene nennen nenne 212 
NMiInstall AR Ee 184 
NMRemoOVê.... sesse sosse esse sedes goed pie eed ke nd 184 
Bo. ER SE IE be EE 224, 249 
OpenResFile...........: irre ior Re Re EG bk tms 232 
OpenRFPeErMm...... sesse sooo esse ERA AE ER SA 232 
Open WD, ose vae n Ka eek eo es Re EE P es de 126 
PACK BIOS Es se ee de DE ee 86, 171 
PB Cat MOVG ives cvcsisssccccentsnvecasidsscedenseacuadncseseczes 226 
PBGeltCatInfo iss eorr ere reg Ge RE Pen eb Gegee 238 
dere di EE heo con 229 
3PBOpenW D. se ss dese dir ee era ee ee ELEC LEE OE 126 
M.inuld E 180 
Ko RE VP eine eder OE ED 161 
Bo c 161 
Boll Me D 193 
PUFSE SPACE ees see Vee eet Ee veggie ge de Per 229 
Put Scrap. see ese Oe E VES SUR ERAN NARRA de ee Ere 180 
-RecoverHandle irisse ses gede gl no se dees dd ede 232 
Ed OE Teo no exar Rt eoe OE es 205 
SetADBINFG. osse se Eg ER FER OR EH oe GR ese 206 
io se. qM 244 
SEtENVIFONS. sessies iiri aeo iE ADR ERU de de doek eke 243 
SetFPOS EE EE I 246 
SelGTOWZONE.. osse ke kan ov eo vee ER ee YVES SR Eg ed 233 
SetMenuBar..... sesse sesse sesse ena nno EE ette tarea noua 180 
SEtWREICON EA OE OS OE Ros 221 
Set ZO AA AE Paz EE 248 
SEGeIFPIIe cs eno eios ré na Pay rea exer ae 205 
S Intinstald EES Se GE DE RE Ke a DNE 221, 257 
Slot V Install... reas retia eN peo aora aee enean 221 
StripAddress ................ eee eene 212, 228, 232 
SwapMMUM ode... ere esose ds ke ke ede nasa rU Ede EED 228 
Ei —————Ó 19 
BELL DD 180 
_SysEnvirons..120, 129, 184, 212, 230, 236, 249, 250 
System Task... issie seide dees ARK dd oo AE Ge dee 248 
nn MED 251 
dd ie. N OE N EA OE a Fes date ride 227 
TICECOUf Loro rea rat re ee LES Ge A NER Ohi 221 
TrackControl sasie Vr err een oap exe E eer PY" 196 
_TrackGOAway ede se ENE E sah so VR eo Wene ode eN Res 247 
Maii 193 
_UnmountVol «5i barbe i epa eoa Leder es ee 180 
UnPackBits AE roi Leonis RE Rea C 86, 171 
WaitNextEvent..............e eere 126, 180, 205 
EA oe d EE OE a PRAG YR Qon EX ESSERE ERE 180 
(Age Ap E 93 
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Sample Compatibility Script Checklist 











Tester's Name CPU Date 
Application Name Version System Software 
SF MF SF MF 

Set Startup Tests Alert Tests 


CJ CO Set Startup to application 

CI O Set Startup to application and DAs 

O O Set Startup to application’s file 

O C] Select About the finder and verify application's 


C] L Restart with unsaved document open to prompt alert 
CJ C Save to a full disk 
O LJ Save to a locked disk 


memory size allocation Font Tests 
T O LJ Select & use at least two Macintosh fonts 
Application Tests O D Select & use at least two LaserWriter fonts 


CJ CJ Open as many applications as is possible 
OO sara layers via Apple menu, icon, and activating 
WS 


O CJ Select & use at least two LQ fonts 
O LJ Select & use at least two third-party downloadable fonts 


win 
CJ Ci Create a new document = = fu s 
OD Save di 
O O Save As 


O O Save in different formats 

O O Use any sample documents 

O CJ Close 

[3 D Quit 

L1 O Open multiple documents 

C) C] Copy, Cut, Paste 

L1] L] Undo 

O O Use Keyboard command equivalents 
O O Paste graphics from Scrapbook. 


Printing Tests 

DO) © Print a document from the application 

O DJ Print selected pages 

C L] Change Page Setup to: Landscape, Enlarged, Reduced, 
and so on 

CJ CJ Print in Background to LaserWriter 

O C Print in Foreground to LaserWriter 

D LJ Print a document from the Finder 

O C Print to all Apple Printers (see Printer Matrix) 














O O Select About (Application) from the Apple menu Additional Tests 
O DO Select About MultiFinder from within the application OO 
O LJ Open all Apple DAs and use briefly DO 
D O Open several third-party DAs and use briefly no 
O L] Play with windows: resize, move, drag offscreen mim 
O LJ Open other applications and switch between layers OD 


O O Use application's text editor to: change font, style, 
size, and so on 


O O Use the Arrow keys 


System Tests 

CJ C Use Disk Init Package from within the application 
O CJ Use Standard File to call Disk Init Package 

C CJ Use Standard File to open a file 

O O Test with RAM Cache On 

LJ DI Test with RAM Cache Off 
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Sampie Compatibility Script Checklist 





* SF = Single Finder, MF = MultiFinder 
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Sample Software and Hardware Matrix 


Application/Version | Date | 









ausi 
roa BEL G 






























SuperDrive BOOK basil bal! 
40MB SCSI 40MB SCSI 800K Color Extended seks 
BOMB SCSI. | 80MB SCSI Multiple 
160MB SCSI | 160MB SCSI Two page 
Ful! page 





General AppleShare WS AT ImageWriter Macintosh 
Color MacsBug 6.0 DC ImageWriter LaserWriter Plus 
Keyboad Responder LaserWriter LQ 

Monitors MacroMaker LaserWriter IISC Adobe 

Mouse Suitcase AT LQ ImageWriter Cassady Ware 
Pyro DC LQ Image Writer 

Sound PrintMonitor 

Startup Device 


System/Finder 
System 


Finder 





Laser Writer AT Image Writer II DC ImageWriter II Circle options 
LaserWriter Plus AT ImageWriter LQ DC ImageWriter LQ ed 


Laser Writer II NTX DC Image Writer 1 8 in 
Laser Writer II NT DC Image Writer 1 15in. AT = AppleTalk 
Laser Writer II SC DC = Direct Connect 
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Developing for International 
Markets 


Tools and Guidelines 


International Development Support 


Intemational Software Development 


This document provides a brief overview of the guidelines you should follow and the 
tools you will need to adapt your products to international markets. 


International markets may be viable ones for your product; therefore, it is important 
that you understand what it means to develop a "localizable" product. Creating a 
localizable product is making sure that your product can be easily translated into 
another language. It also means adhering to country-specific standards such as time, 
date, currency, and sorting sequences. During "localization" your application and its 
accompanying documentation are translated and adapted to a country's culture and 
standards (for example: right-to-left or left-to-right text handling, commas versus 
periods as decima! separators, and appropriate currency symbols). 

The ease with which a product can be localized will vary depending upon 
the overall design of the product. Placing text in resources is one of the signs of a 
well-designed product because it facilitates the localization process. Apple has 
created the following tools to facilitate the design of localizable products and the 
localization process. 


* The most important rule is to follow the programming guidelines set forth in 
Inside Macintosh, available from APDA™, especially Volumes I and V, which 
contain calls to the International Utilities (date, time, number formats, and so on) 
and to the Script Manager for Roman text handling, such as French, Italian, 
Spanish, and non-Roman text handling, such as Japanese, Arabic, and Hebrew. 
Also included is a section on the International Human Interface Guidelines. 

¢ Other guidelines can be found in the alpha draft of the Software Development for 
International Markets manual. This manual, also available from APDA, explains 

, the things that you need to consider during the design stage, as well as which 
i tools you should use during the development phase. It also describes the 
localization tools and how to use them. 

* The Localizability Checklist, following this document, is a guideline for world- 
wide product development. It should be used before, during, and after you 
complete the development of your product to make sure you are addressing all 
the localizability issues. For detailed information on each item or area, refer to 
the Software Development for International Markets manual, available from 
APDA. 

e In addition to the documentation mentioned above, you should use the follow- 
ing tools: 


Script Manager Developer's Package 

The Script Manager Developer's Package, available from APDA™ contains docu- 
mentation and tools to aid you in writing and testing applications that are 
compatible with the Script Manager. The Script Manager allows Macintosh 
applications to handle Roman and non-Roman scripts correctly. It also supplies 
a number of routines that aid in text handling in general. For more information 
on Script Manager, see the Script Manager document in this section. 
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Support Programs 


International Development Support 


ResEdit 

As Apple's resource editor, ResEdit allows you to create and edit resources such 
as menus and menu items, strings, icons, windows, dialogue boxes, and alert 
messages. Itis used in the localization process to translate resources. ResEdit 
is an indispensable tool for all developers, and it is also available from APDA™ 


Localized System Software 

To ensure that your product is fully localizable, you will need to test it with one 
or more foreign-language versions of the system software. Apple has released 
25 localized versions of the system software which are available from APDA™ 
When you are ready to market your product overseas, contact Apple's Software 
Licensing Department to license your system software. 


Glossaries 

The foreign language glossaries provide the translations of the most commonly 
used terms, such as menu, edit, and cut and paste. You will find the glossaries 
on Phil and Dave's Excellent CD available quarterly in the Developer Programs' 
monthly mailing or on the AppleLink network [path: Developer Technical 
Supports Macintosh: Tools: Translate itl] The languages that are currently 
available are Dutch, German, Finnish and Italian. 


Technical Notes 
Macintosh Technical Notes contain detailed information written by the Macin- 
tosh Developer Technical Support Group. The notes expand and clarify 
Apples documentation, including errors found in software, hardware and 
manuals. They also contain commonly asked developer questions. 

Of particular interest to worldwide product development are the 
following international specific technical notes: 


138 Using KanjiTalk with a non-Japanese Macintosh Plus 
153 Changes in Intemational Utilities and Resources 
174 Accessing the Script Manager Print Action Routine 

| 178 Modifying the Standard String Comparision 

| 182 How to Construct Word-Break Tables 


Technical Notes are available through the following channels: 


* Developer Programs’ monthly mailings 

e The AppleLink network, Macintosh: (path: Developer Technical Support: 
Macintosh: Technical Notes] Apple IT: [path: Developer Technical Support: 
Apple II: Technical Notes] 

*  APDA 


The Developer Programs and Developer Technical Support groups at Apple are 
committed to supporting your efforts to create localizable products and to distribut- 
ing your products overseas. So that you can benefit from our experience, we 
recommend that you contact us during the design stage of your product. As you 
approach the distribution, marketing, and localization Stages, we will also make 
sure that you receive the support and guidance you need from our international 
subsidiaries. 
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Localizability Checklist 


The following checklist is being provided as a guideline for worldwide product 
development. It should be used before, durin , and after the development of your 
product to make sure you are addressing all of the localizability issues. For detailed 
information on each item or area, refer to the Software Development for International 
Markets manual, available through APDA™ 


Text contained in the application/DA/driver/and so on 
The following should be in resources: 


ALL text (including special characters, delimiters, and so on) 

Lengths of string and text resources 

Menus and power keys 

Character/word/phrase/text translators (tables) 

Address formats, including "ZIP" codes and phone numbers 

Text data compaction, encoding, and transmission must allow character codes 
from $20 to $FF to be used. 


When creating your resources, keep in mind: 


* Text needs room to grow (up, down, and sideways) 
— Translated text data is often 50 percent larger than the U.S. English text 
data. 
— Diacritical marks, widely used outside the United States, extend up to the 
ascent line. 
— Some system fonts contain characters that extend to both ascent and descent 
lines. 
* Potential grammar problems (error messages, "natural" programming language 
. Structures, and so on). 
* Text location within a window should be easy to change. 


Text handling 
Use the Script Manager for: 


* Word Boundaries (word wrap, selection, search, and cut and paste). 

* Character Boundaries (search, replace, sort, word wrap, backspace, delete, and 
cut and paste). 

*  Right-to-left and mixed-direction text (justification, cursor positioning, highlight- 
ing). 


* Displaying font names in the proper font. 


International Development Support Localizability Checklist 5-4 


Remember: 


e Use TextEdit and Dialog Manager for all text handling (preferred). 

* Font #0 is not always Chicago. 

e Use system and application fonts (0,1) when the user cannot select the font. 

* Avoid hard-coded font sizes (if you must, use a font size of 0; otherwise, let the 
user choose). 

* When using fonts to provide symbols, use proper font ID numbers as defined by 
International System Software. 

Formats and special symbols/words 

Use the International Utilities for: 

e Searching 

* Sorting 


* Formats and separators for: 
— Numbers (decimal mark, and so on). 
— Dates (short, long form, calendars— European, non-Gregorian). 
— Time formats (12 hr, 24 hr, AM/PM and so on), 

* Units of measure (currency, metric vs. nonmetric), 


Additional data that needs to be localizable 


* Keep in mind that some countries perform financial calculations differently. 
* Graphics and icons (mailboxes, champagne bottles, and so on) should be in 
resources. 


Additional issues 
Use Script Manager for: 


* Properly changing the current script and the key script when needed. 
e Changing the case of text (lowercase or u ppercase)—use Transliterate. 


Script Interface System-related issues: 


* Hiding the Menu Bar (script icon)—save and restore MBarHeight. 
e Don'tuse <Command><Space> (and arrow keys) for Command-key equivalents. 
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For more e information on ba lizing your products, Contact: 


ake Mauro Ugazio 


ee Developer Technical Support 


Apple Computer s.p.a. 

Via Rivoltana, & 

2090 Segrare Milano ITALY 

Tel. (02) 75741 - Tx 530173 APPLE I 
Fax (02) 7534303 - A.Link ITA.DTS 
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€, Macintosh’ Technical Notes 


HyperCard" Stack 1985-88 
Version 5.0 


This package contains: 





1 Manual Macintosh Technical Notes Stack User's Guide 1985-88 
1 Set of Release Notes Maciniosh Technical Notes 1985-88 
2 Disks Macintosh Technical Notes, HyperCard Stack 1985-88, Disk 1 


Macintosh Technical Notes, HyberCard Stack 1985-88, Disk 2 


[f you have any questions, please call: 


1-800-282-2732 (U.S.) 
1-408-562-3910 (International 
1-800-637-0029 (Canada) 


M0215LL/A 6/15/89 


